@sandrinio/vbounce 1.0.0 → 1.2.0

package/brains/claude-agents/architect.md

@@ -130,6 +130,24 @@ When the Team Lead asks for a **Sprint Integration Audit** (after all stories pa
 - Check for emergent coupling that wasn't visible in individual story reviews
 - Write the integration audit to `.bounce/reports/sprint-integration-audit.md`
 
+## Checkpointing
+
+After completing each major phase of your audit (e.g., Deep Audit done, Trend Check done, ADR compliance checked), write a progress checkpoint to `.bounce/reports/STORY-{ID}-arch-checkpoint.md`:
+
+```markdown
+# Architect Checkpoint: STORY-{ID}
+## Completed
+- {Which audit phases are done}
+## Remaining
+- {Which phases are left}
+## Preliminary Findings
+- {Key issues or observations so far}
+## Current Verdict
+- {Leaning PASS/FAIL and why}
+```
+
+This enables recovery if your session is interrupted. A re-spawned Architect agent reads the checkpoint to continue without re-running completed audit phases. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER fix code. You only report what needs fixing.

package/brains/claude-agents/developer.md

@@ -61,6 +61,24 @@ Write a **Developer Implementation Report** to `.bounce/reports/STORY-{ID}-dev.m
 - [ ] No new patterns or libraries introduced
 ```
 
+## Checkpointing
+
+After completing each major phase of your work (e.g., initial implementation done, tests written, bug fixes applied), write a progress checkpoint to `.bounce/reports/STORY-{ID}-dev-checkpoint.md`:
+
+```markdown
+# Developer Checkpoint: STORY-{ID}
+## Completed
+- {What's done so far}
+## Remaining
+- {What's left to do}
+## Key Decisions
+- {Important choices made during implementation}
+## Files Modified
+- {List of files changed so far}
+```
+
+This enables recovery if your session is interrupted. A re-spawned Developer agent reads the checkpoint to continue without restarting from scratch. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER communicate with QA or Architect directly. Your report is your only output.

package/brains/claude-agents/qa.md

@@ -41,6 +41,14 @@ Run Story §2.1 Gherkin scenarios against the implementation:
 - Each scenario is a binary pass/fail
 - Document exact failure conditions (input, expected, actual)
 
+### Spec Fidelity Check
+After running scenarios, verify:
+- Test count matches the number of Gherkin scenarios in §2 (not fewer, not more)
+- Fixture data matches spec examples (if spec says "5 items", test uses 5 items)
+- API contracts match §3 exactly (methods, parameters, return types)
+
+If there's a mismatch, flag it — even if the tests pass. Passing tests with wrong fixture counts means the tests aren't validating what the spec intended.
+
 ### Gold-Plating Audit
 Check for unnecessary complexity the Developer added beyond the Story spec:
 - Features not in the requirements
@@ -74,6 +82,16 @@ Write a **QA Validation Report** to `.bounce/reports/STORY-{ID}-qa.md`:
 ## Gold-Plating Audit
 - {Findings or "No gold-plating detected"}
 
+## Scrutiny Log
+- **Hardest scenario tested**: {Which scenario was closest to failing and why}
+- **Boundary probed**: {What edge case did you push hardest on}
+- **Observation**: {Anything that passed but felt fragile — worth watching in future sprints}
+
+## Spec Fidelity
+- Test count matches Gherkin scenarios: {Yes/No — if No, list discrepancies}
+- Fixture data matches spec examples: {Yes/No}
+- API contracts match §3: {Yes/No}
+
 ## Recommendation
 PASS — Ready for Architect review.
 ```
@@ -103,6 +121,24 @@ Every finding must include a non-coder analogy. Examples:
 - "High coupling" → "Pulling one wire takes down the whole electrical system"
 - "Duplication" → "Three departments each built their own payroll system"
 
+## Checkpointing
+
+After completing each major phase of your testing (e.g., Quick Scan done, PR Review done, scenarios validated), write a progress checkpoint to `.bounce/reports/STORY-{ID}-qa-checkpoint.md`:
+
+```markdown
+# QA Checkpoint: STORY-{ID}
+## Completed
+- {Which testing phases are done}
+## Remaining
+- {Which phases are left}
+## Preliminary Findings
+- {Issues found so far, scenarios passed/failed}
+## Current Verdict
+- {Leaning PASS/FAIL and why}
+```
+
+This enables recovery if your session is interrupted. A re-spawned QA agent reads the checkpoint to continue without re-running completed test phases. Overwrite the checkpoint file each time — only the latest state matters.
+
 ## Critical Rules
 
 - You NEVER fix code. You only report what's broken.

package/docs/HOTFIX_EDGE_CASES.md

@@ -0,0 +1,37 @@
+# Hotfix Workflow: Edge Cases & Mitigations
+
+This document outlines the critical edge cases, failure modes, and required mitigations for the **V-Bounce OS Hotfix (L1 Trivial)** workflow.
+
+---
+
+## 1. Scope Creep (The "Just one more file" Fallacy)
+
+*   **The Edge Case**: A request triaged as a Hotfix (e.g., "Fix button color") turns out to be more complex (e.g., the component is shared across 5 views, requires updating global CSS variables, and affects existing tests).
+*   **The Mitigation**: 
+    *   **Mitigation — Developer Hard-Stop**: The Developer agent must stop if a fix requires touching >2 files or introduces new logic patterns.
+*   **Mitigation — Escalation to Human**: The Team Lead must escalate the issue back to the Human, providing suggestions and recommendations on how to proceed (e.g., converting to a standard Epic/Story).
+
+## 2. The "Silent Regression" (Bypassing QA)
+
+*   **The Edge Case**: Bypassing the QA and Architect agents allows a "quick fix" to inadvertently break a downstream component that a human might miss during manual verification.
+*   **The Mitigation**:
+    *   **Mitigation — Automated Validation**: Mandate in `hotfix.md` that the Developer must run localized tests (`npm test`) before submission.
+*   **Mitigation — Manual Human Testing**: Because the hotfix bypasses the QA agent, the Human MUST test the fix manually. This includes verifying surrounding features and the overall context, not just the isolated fix.
+
+## 3. Architectural Drift (The "Death by a Thousand Papercuts")
+
+*   **The Edge Case**: A series of un-audited hotfixes introduces minor anti-patterns (e.g., inline styles instead of Tailwind classes), degrading codebase integrity over time.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Trend Check (`hotfix-manager audit`)**: To save tokens, an automated bash script runs static analysis (grepping for inline styles, `console.log`, and bypasses) on Hotfix commits before Sprint Integration, raising flags only if anti-patterns are detected.
+
+## 4. Merge Conflicts with Active Worktrees
+
+*   **The Edge Case**: A hotfix merged directly to the `sprint` branch causes a collision when other agents try to merge their isolated `.worktrees/`.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Worktree Sync (`hotfix-manager sync`)**: After a Hotfix merge, a script safely detects all active `.worktrees/` and runs a `git pull --rebase` to ensure parallel agents are building on the latest code.
+
+## 5. Invisible Deliverables (The Ghost Fix)
+
+*   **The Edge Case**: Hotfixes bypass the `DELIVERY_PLAN.md`, so they are excluded from the Sprint Report and user-facing documentation.
+*   **The Mitigation**:
+    *   **Mitigation — Scripted Ledger (`hotfix-manager ledger`)**: An automated script appends a new row (Title and Brief Description) to the **"§8 Applied Hotfixes"** table in the `DELIVERY_PLAN.md` specifically for Scribe integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {
@@ -35,6 +35,8 @@
     "bin",
     "brains",
     "templates",
-    "skills"
+    "skills",
+    "scripts",
+    "docs"
   ]
 }

package/scripts/hotfix_manager.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+
+# V-Bounce OS: Hotfix Manager
+# Handles edge cases for L1 Trivial tasks to save tokens and ensure framework integrity.
+
+set -euo pipefail
+
+# Ensure we're in a git repository
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo "❌ Error: Not inside a git repository."
+    exit 1
+}
+
+COMMAND="${1:-}"
+
+function show_help {
+    echo "V-Bounce OS — Hotfix Manager"
+    echo ""
+    echo "Usage: ./scripts/hotfix_manager.sh <command> [args]"
+    echo ""
+    echo "Commands:"
+    echo "  audit               Run a lightweight static analysis on recent commits to detect architectural drift."
+    echo "  sync                Rebase all active git worktrees against the current sprint branch."
+    echo "  ledger <title> <desc>  Append a Hotfix entry to §8 Applied Hotfixes in the active DELIVERY_PLAN.md."
+    echo ""
+    echo "Examples:"
+    echo "  ./scripts/hotfix_manager.sh audit"
+    echo "  ./scripts/hotfix_manager.sh sync"
+    echo "  ./scripts/hotfix_manager.sh ledger \"Fix Header\" \"Aligned the logo to the left\""
+    exit 1
+}
+
+if [ -z "$COMMAND" ]; then
+    show_help
+fi
+
+case "$COMMAND" in
+    audit)
+        echo "🔍 Running Token-Saving Hotfix Audit..."
+
+        # Determine how many commits exist on the branch so we don't overshoot
+        TOTAL_COMMITS=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+        LOOKBACK=5
+        if [ "$TOTAL_COMMITS" -lt "$LOOKBACK" ]; then
+            LOOKBACK="$TOTAL_COMMITS"
+        fi
+
+        if [ "$LOOKBACK" -eq 0 ]; then
+            echo "✅ No commits to audit."
+            exit 0
+        fi
+
+        SUSPICIOUS=$(git diff "HEAD~${LOOKBACK}" HEAD -G'style=|console\.log|// TODO' --name-only 2>/dev/null || true)
+
+        if [ -n "$SUSPICIOUS" ]; then
+            echo "⚠️  WARNING: Potential architectural drift detected in recent commits."
+            echo "The following files contain inline styles, console.logs, or TODOs:"
+            echo "$SUSPICIOUS"
+            echo ""
+            echo "Action Required: The Architect agent MUST perform a Deep Audit on these files."
+            exit 1
+        else
+            echo "✅ No obvious architectural drift detected in recent commits."
+            exit 0
+        fi
+        ;;
+
+    sync)
+        echo "🔄 Syncing active worktrees with the latest changes..."
+
+        WORKTREE_DIR="${REPO_ROOT}/.worktrees"
+
+        if [ ! -d "$WORKTREE_DIR" ]; then
+            echo "✅ No active worktrees found at ${WORKTREE_DIR}. Nothing to sync."
+            exit 0
+        fi
+
+        CURRENT_BRANCH=$(git branch --show-current)
+
+        if [ -z "$CURRENT_BRANCH" ]; then
+            echo "❌ Error: Detached HEAD state. Cannot determine sprint branch for sync."
+            exit 1
+        fi
+
+        SYNC_COUNT=0
+        FAIL_COUNT=0
+
+        for dir in "${WORKTREE_DIR}"/*/; do
+            if [ -d "$dir" ]; then
+                WORKTREE_NAME=$(basename "$dir")
+                echo "Syncing worktree: $WORKTREE_NAME..."
+
+                if (cd "$dir" && git fetch origin && git rebase "origin/$CURRENT_BRANCH"); then
+                    echo "  ✅ Successfully synced $WORKTREE_NAME."
+                    SYNC_COUNT=$((SYNC_COUNT + 1))
+                else
+                    echo "  ❌ Failed to sync $WORKTREE_NAME. Manual intervention required."
+                    FAIL_COUNT=$((FAIL_COUNT + 1))
+                fi
+            fi
+        done
+
+        echo ""
+        echo "Sync complete: $SYNC_COUNT succeeded, $FAIL_COUNT failed."
+        [ "$FAIL_COUNT" -gt 0 ] && exit 1 || exit 0
+        ;;
+
+    ledger)
+        TITLE="${2:-}"
+        DESC="${3:-}"
+
+        if [ -z "$TITLE" ] || [ -z "$DESC" ]; then
+            echo "❌ Error: Missing title or description for the ledger."
+            echo "Usage: ./scripts/hotfix_manager.sh ledger \"Fix Header\" \"Aligned the logo to the left\""
+            exit 1
+        fi
+
+        # Find the active delivery plan (search from repo root)
+        DELIVERY_PLAN=$(find "${REPO_ROOT}/product_plans" -name "DELIVERY_PLAN.md" 2>/dev/null | head -n 1)
+
+        if [ -z "$DELIVERY_PLAN" ]; then
+            echo "❌ Error: No DELIVERY_PLAN.md found in product_plans/."
+            exit 1
+        fi
+
+        echo "📝 Updating Hotfix Ledger in $DELIVERY_PLAN..."
+
+        # Check if §8 Applied Hotfixes exists, if not, create it
+        if ! grep -q "## 8. Applied Hotfixes" "$DELIVERY_PLAN"; then
+            echo "" >> "$DELIVERY_PLAN"
+            echo "---" >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "## 8. Applied Hotfixes" >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "> L1 Trivial fixes that bypassed the Epic/Story hierarchy. Auto-appended by \`hotfix_manager.sh ledger\`." >> "$DELIVERY_PLAN"
+            echo "" >> "$DELIVERY_PLAN"
+            echo "| Date | Title | Brief Description |" >> "$DELIVERY_PLAN"
+            echo "|------|-------|-------------------|" >> "$DELIVERY_PLAN"
+        fi
+
+        # Append the new row
+        DATE=$(date "+%Y-%m-%d")
+        echo "| $DATE | $TITLE | $DESC |" >> "$DELIVERY_PLAN"
+
+        echo "✅ Ledger updated: \"$TITLE\" added to §8 Applied Hotfixes."
+        ;;
+
+    --help|-h|help)
+        show_help
+        ;;
+
+    *)
+        echo "❌ Unknown command: $COMMAND"
+        echo ""
+        show_help
+        ;;
+esac

package/skills/agent-team/SKILL.md

@@ -201,7 +201,13 @@ Examples:
    e. DevOps runs `hotfix_manager.sh sync` to update any active story worktrees.
    f. Update Delivery Plan Status to "Done".
 
-6. Update DELIVERY_PLAN.md: Sprint Status → "Active"
+6. **Parallel Readiness Check** (before bouncing multiple stories simultaneously):
+   - Verify test runner config excludes `.worktrees/` (vitest, jest, pytest, etc.)
+   - Verify no shared mutable state between worktrees (e.g., shared temp files, singletons writing to same path)
+   - Verify `.gitignore` includes `.worktrees/`
+   If any check fails, fix before spawning parallel stories. Intermittent test failures from worktree cross-contamination erode trust in the test suite fast.
+
+7. Update DELIVERY_PLAN.md: Sprint Status → "Active"
 ```
 
 ### Step 1: Story Initialization
@@ -215,6 +221,7 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
 - Read LESSONS.md
 - Check RISK_REGISTRY.md for risks tagged to this story or its Epic
 - If `product_documentation/_manifest.json` exists, identify docs relevant to this story's scope (match against manifest descriptions/tags). Include relevant doc references in the task file so the Developer has product context.
+- **Adjacent implementation check:** For stories that modify or extend modules touched by earlier stories in this sprint, identify existing implementations the Developer should reuse. Add to the task file: `"Reuse these existing modules: {list with file paths and brief description of what each provides}"`. This prevents agents from independently re-implementing logic that already exists — a common source of duplication when stories run in parallel.
 - Create task file in `.worktrees/STORY-{ID}/.bounce/tasks/`
 - Update DELIVERY_PLAN.md: V-Bounce State → "Bouncing"
 
@@ -224,6 +231,7 @@ mkdir -p .worktrees/STORY-{ID}/.bounce/{tasks,reports}
    - Story §1 The Spec + §3 Implementation Guide
    - LESSONS.md
    - Relevant react-best-practices rules
+   - Adjacent module references (if any — "reuse src/core/X.ts for Y")
 2. Developer writes code and Implementation Report to .bounce/reports/
 3. Lead reads report, verifies completeness
 ```
@@ -295,7 +303,12 @@ After ALL stories are merged into `sprint/S-01`:
 2. Generate Sprint Report to .bounce/sprint-report.md
 3. V-Bounce State → "Sprint Review" for all stories
 4. Present Sprint Report to human
-5. After approval → Spawn devops subagent for Sprint Release:
+5. **BLOCKING STEP — Lesson Approval:**
+   Review and approve/reject ALL flagged lessons from §4 of the Sprint Report.
+   Do NOT proceed to Sprint Release until every lesson has a status of "Yes" or "No".
+   Stale lessons lose context — approve them while the sprint is fresh.
+   Present each lesson to the human and record approved ones to LESSONS.md immediately.
+6. After approval → Spawn devops subagent for Sprint Release:
    - Merge sprint/S-01 → main (--no-ff)
    - Tag release: v{VERSION}
    - Run full test suite + build + lint on main

package/skills/doc-manager/SKILL.md

@@ -234,8 +234,7 @@ Any → Parking Lot: Deferred by decision
 
 ***HOTFIX TRANSITIONS***
 Draft → Bouncing: Hotfix template created + Triage confirmed L1
-Bouncing → Done: Dev implements + Human manually verifies
-Done → Sync: `hotfix_manager.sh sync` run to update other worktrees
+Bouncing → Done: Dev implements + Human manually verifies + DevOps runs `hotfix_manager.sh sync`
 ```
 
 ## Agent Integration

package/skills/file-organization/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: file-organization
+description: "**Codebase Cleanliness Standard**: Enforces clean file organization in any codebase. Before creating ANY file, classify it by intent—deliverables go to the project tree, working artifacts go to `/temporary/`. Before committing, review `git diff` to catch misplaced files. Use this skill whenever creating, moving, or committing files. Works with all languages and frameworks. The `/temporary/` folder is git-ignored so working artifacts never get merged. ALWAYS consult this skill when writing files to the repo—it prevents clutter from debug scripts, scratch analysis, throwaway tests, and other AI working artifacts from polluting the codebase."
+compatibility: "Git required. Works with any language or framework."
+---
+
+## Core Principle
+
+Every file you create has an **intent**. You always know why you're creating it. Use that knowledge.
+
+- **"I'm creating this because the user asked for it / it solves the task"** → Project tree (root, src/, etc.)
+- **"I'm creating this to help me work — debug, analyze, test an idea"** → `/temporary/`
+
+This is not about file types or extensions. A `.test.js` file might be a critical part of the test suite, or it might be a throwaway script you wrote to check a theory. The difference is intent.
+
+## Layer 1: Proactive — Decide at Creation Time
+
+Before writing any file, run this mental check:
+
+```
+WHY am I creating this file?
+│
+├─ DELIVERABLE — The user asked for this, or it directly fulfills the task
+│  Examples:
+│  - "Add input validation" → validation.ts (deliverable)
+│  - "Write unit tests for auth" → auth.test.ts (deliverable)
+│  - "Create a migration for the new table" → 003_add_users.sql (deliverable)
+│  - "Update the README" → README.md (deliverable)
+│  → CREATE IN PROJECT TREE
+│
+└─ WORKING ARTIFACT — I need this to help me understand, debug, or explore
+   Examples:
+   - Script to reproduce a bug → debug-repro.py (working artifact)
+   - Markdown notes analyzing the codebase → analysis.md (working artifact)
+   - Quick test to verify an assumption → check-behavior.js (working artifact)
+   - Output log from a test run → output.txt (working artifact)
+   → CREATE IN /temporary/
+```
+
+The question is never "what type of file is this?" — it's **"does this file exist to serve the project, or to serve my working process?"**
+
+## Layer 2: Reactive — Safety Net Before Commit
+
+Before committing, review what you've changed. This catches anything that slipped through Layer 1.
+
+```bash
+git diff --name-only
+git status
+```
+
+For each file in the diff, ask:
+
+1. **Did the user's task require this file?** If no → move to `/temporary/`
+2. **Does this file exist in the project already?** If yes, you're editing existing code — that's fine, leave it
+3. **Is this a new file I created to help myself work?** If yes → move to `/temporary/`
+
+### Example: "Fix the login bug"
+
+```bash
+$ git status
+  modified:   src/auth/login.ts          # ← The actual fix. Commit this.
+  new file:   debug-login.py             # ← Script I wrote to reproduce the bug. Move to /temporary/
+  new file:   test-output.log            # ← Output from my debugging. Move to /temporary/
+  modified:   src/auth/login.test.ts     # ← Updated existing test. Commit this.
+```
+
+After cleanup:
+```bash
+$ git status
+  modified:   src/auth/login.ts          # ✅ commit
+  modified:   src/auth/login.test.ts     # ✅ commit
+```
+
+The debug script and log are now safely in `/temporary/`, out of the commit.
+
+### Example: "Add user validation with tests"
+
+```bash
+$ git status
+  new file:   src/validation/validate.ts       # ← Deliverable. Commit.
+  new file:   src/validation/validate.test.ts  # ← User asked for tests. Commit.
+  new file:   scratch-regex-test.js            # ← I wrote this to test regex patterns. /temporary/
+```
+
+Notice how `validate.test.ts` stays because the user asked for tests — it's a deliverable. But `scratch-regex-test.js` was a working artifact.
+
+## Language-Agnostic — Why Intent Beats File Types
+
+Static file-type rules break across languages:
+
+- Python's `__pycache__/` is already gitignored — don't touch it
+- Java's `target/` is a build artifact — handled by existing `.gitignore`
+- A Go `vendor/` directory might be intentionally committed
+- Database migrations are generated but absolutely committed
+- Protocol buffer outputs, GraphQL codegen — generated but part of the codebase
+- `dist/` and `build/` directories vary by project
+
+Trying to categorize by extension or directory name is fragile. Instead, the intent check works universally:
+
+**"Did I create this to deliver the task, or to help myself work?"**
+
+This one question works whether you're writing Python, TypeScript, Rust, Go, Java, C#, or anything else.
+
+## Things That Are NEVER Working Artifacts
+
+Don't accidentally move these to `/temporary/`:
+
+- Existing files you modified (they're already tracked in git)
+- Test suites the project already has (`tests/`, `__tests__/`, `spec/`)
+- CI/CD configs (`.github/workflows/`, `Dockerfile`, etc.)
+- Lock files (`package-lock.json`, `Cargo.lock`, `poetry.lock`)
+- Migration files (database schema changes)
+- Generated code that the project commits (codegen output, protobuf, etc.)
+- Config files (`.eslintrc`, `tsconfig.json`, `pyproject.toml`)
+
+If a file already exists in the git tree, it belongs there. Your job is only to route **new files you create** during your working process.
+
+## Git Setup
+
+Add `/temporary/` to `.gitignore` if it's not there already:
+
+```gitignore
+# AI/developer working artifacts (never commit)
+/temporary/
+```
+
+This is a one-time setup. After this, anything in `/temporary/` is invisible to git.
+
+## Quick Reference
+
+```
+BEFORE CREATING A FILE:
+  "Is this a deliverable?"  → YES → project tree
+                             → NO  → /temporary/
+
+BEFORE COMMITTING:
+  Run: git diff --name-only
+  For each NEW file: "Did the task require this?" → NO → mv to /temporary/
+  For MODIFIED files: leave them (they're already tracked)
+```
+
+## Why This Matters
+
+Working artifacts in the root folder create real problems: teammates see debug scripts and think they're production code, CI might pick up stray test files, code review gets cluttered with irrelevant changes, and over time the repo becomes a mess of half-finished experiments mixed with real code.
+
+The `/temporary/` folder gives you a safe space to work freely. Use it for anything and everything you need during your process — it never touches the git history and never confuses anyone.

package/skills/file-organization/TEST-RESULTS.md

@@ -0,0 +1,193 @@
+# File Organization Skill — Eval Results
+
+## Eval 1: Repro Script vs. Handler Fix
+
+**Prompt:** "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?"
+
+**Expected Output:** The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.
+
+**Relevant Guidance:**
+- "Script to reproduce a bug → debug-repro.py (working artifact)" (Line 33)
+- "I'm creating this because the user asked for it / it solves the task" → Project tree (Line 11)
+- "I'm creating this to help me work — debug, analyze, test an idea" → /temporary/ (Line 12)
+
+**Analysis:**
+The skill clearly distinguishes between debugging artifacts ("Script to reproduce a bug") and actual fixes. An agent following the core principle would recognize:
+- The Python script's intent: "help me understand/debug" → /temporary/
+- The handler fix's intent: "solves the task" → project tree
+
+The guidance is unambiguous. The agent gets the correct answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 2: User-Requested Tests vs. Scratch File
+
+**Prompt:** "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?"
+
+**Expected Output:** The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Write unit tests for auth" → auth.test.ts (deliverable) (Line 26)
+- "Add user validation with tests" example shows validate.test.ts as deliverable because "User asked for tests" (Line 85)
+- "Quick test to verify an assumption → check-behavior.js (working artifact)" (Line 35)
+
+**Analysis:**
+The skill explicitly handles this distinction in the "Add user validation with tests" example (Lines 76-85), which directly parallels Eval 2:
+- User-requested tests (validate.test.ts) = deliverable
+- Scratch working files (scratch-regex-test.js) = working artifact
+
+The key insight is whether **the user asked for** the tests. The skill states this clearly. An agent would correctly identify:
+- User explicitly asked for unit tests → deliverable
+- Regex pattern scratch file is "to help me work" (testing an assumption) → working artifact
+
+**Potential gap:** The skill doesn't address a borderline case where scratch tests could be mistaken for part of the test suite if the agent isn't careful about the "user asked for" criterion. However, the stated guidance is clear enough.
+
+**Rating: PASS**
+
+---
+
+## Eval 3: Existing Tracked Tests vs. Debug Script
+
+**Prompt:** "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?"
+
+**Expected Output:** Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.
+
+**Relevant Guidance:**
+- "Existing files you modified (they're already tracked in git)" — Never working artifacts (Line 108)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+- "If a file already exists in the git tree, it belongs there. Your job is only to route **new files you create** during your working process." (Line 116)
+
+**Analysis:**
+The skill explicitly states that existing tracked files are "NEVER working artifacts" and gives `tests/` as a direct example. For check-api.sh, the intent is clear: debug artifact, not user-requested deliverable.
+
+An agent would correctly identify:
+1. tests/ is already tracked → don't touch it
+2. check-api.sh intent: "to help me debug" → /temporary/
+
+The guidance is explicit and unambiguous. The agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 4: Generated-but-Committed Migration vs. Analysis Notes
+
+**Prompt:** "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?"
+
+**Expected Output:** The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.
+
+**Relevant Guidance:**
+- "Database migrations are generated but absolutely committed" (Line 94)
+- "Migration files (database schema changes)" — Never working artifacts (Line 112)
+- "Markdown notes analyzing the codebase → analysis.md (working artifact)" (Line 34)
+
+**Analysis:**
+The skill handles this well. It explicitly recognizes that "generated" doesn't mean "working artifact" — migrations are generated by the ORM but belong in the project because they're **part of the deliverable** (schema changes that must be committed).
+
+For the migration file: The skill states directly "Migration files (database schema changes)" as something that is never a working artifact.
+
+For analysis.md: The skill lists "Markdown notes analyzing the codebase → analysis.md (working artifact)" — this directly matches the evaluation scenario.
+
+An agent would correctly identify:
+1. Migration file: "the project commits this" + "database schema changes" → project tree
+2. analysis.md: "notes analyzing the codebase" + "to help me work" → /temporary/
+
+The guidance is explicit and covers both cases directly.
+
+**Rating: PASS**
+
+---
+
+## Eval 5: Requested Component vs. Debug Render vs. Existing Test Suite
+
+**Prompt:** "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?"
+
+**Expected Output:** The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.
+
+**Relevant Guidance:**
+- "The user asked for it / it solves the task" → Project tree (Line 11)
+- "I need this to help me understand, debug, or explore" → /temporary/ (Line 31)
+- "Test suites the project already has (`tests/`, `__tests__/`, `spec/`)" — Never working artifacts (Line 109)
+
+**Analysis:**
+This eval tests three things:
+1. **Requested component:** Clear deliverable intent
+2. **Debug render file:** Clearly a working artifact ("test how it renders in isolation" = debugging/exploring)
+3. **Existing __tests__/ folder:** Explicitly listed as something to never move
+
+The skill handles all three. The guidance is clear. An agent would get the right answer.
+
+**Rating: PASS**
+
+---
+
+## Eval 6: Git Status Cleanup (Layer 2)
+
+**Prompt:** "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?"
+
+**Expected Output:** Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).
+
+**Relevant Guidance:**
+- Layer 2 reactive check (Lines 42-55)
+- "Did the user's task require this file? If no → move to /temporary/" (Line 53)
+- "Does this file exist in the project already? If yes, you're editing existing code — that's fine, leave it" (Line 54)
+- "Is this a new file I created to help myself work? If yes → move to /temporary/" (Line 55)
+- Example showing git status cleanup (Lines 57-74) with similar structure
+
+**Analysis:**
+The skill provides the Layer 2 reactive framework directly:
+1. **modified users.ts:** Already tracked → commit
+2. **new users.test.ts:** User asked for tests (stated in prompt) → commit
+3. **new output.log:** Created during working process (debug output) → /temporary/
+4. **new temp-check.py:** Name itself suggests "to help myself work" + temporary → /temporary/
+
+The example (Lines 57-74) shows the exact scenario structure. The three questions in Layer 2 map directly:
+- Q1 (did user ask?): No for output.log and temp-check.py → move
+- Q2 (already exists?): No for new files, but users.ts exists → commit users.ts
+- Q3 (new artifact?): Yes for output.log and temp-check.py → move
+
+An agent would get the right answer following the Layer 2 framework.
+
+**Rating: PASS**
+
+---
+
+## Summary Assessment
+
+| Eval | Result | Confidence | Notes |
+|------|--------|-----------|-------|
+| 1 | PASS | High | Clear distinction between debug script and fix |
+| 2 | PASS | High | Explicit example matches eval scenario |
+| 3 | PASS | High | Existing files explicitly excluded from working artifacts |
+| 4 | PASS | High | Migrations explicitly covered; analysis.md directly exemplified |
+| 5 | PASS | High | All three elements (new component, debug file, existing suite) handled clearly |
+| 6 | PASS | High | Layer 2 framework provides exact decision tree; example mirrors scenario |
+
+## Critical Findings
+
+**All evals achieve PASS.** The skill provides:
+
+1. **Clear intent-based framework** that works across all scenarios
+2. **Explicit examples** that map directly to evals 2, 4, 5, and 6
+3. **Direct lists** of files that are "NEVER working artifacts," covering edge cases in evals 3 and 5
+4. **Layer 2 reactive checks** that handle the git status scenario (eval 6) with a concrete decision tree
+5. **Explicit handling of "generated but committed"** files like migrations (eval 4)
+
+The skill successfully distinguishes user-requested deliverables from working artifacts across all cases. Agents following either Layer 1 (proactive) or Layer 2 (reactive) would arrive at correct answers for all six evals.
+
+### Strengths of the Skill
+
+- **Not file-type dependent:** The "intent" approach works for all scenarios without fragile extension-based rules
+- **Handles edge cases explicitly:** Migrations, codegen, existing tracked files all explicitly addressed
+- **Concrete examples:** Evals 2, 4, 5 are nearly identical to skill examples
+- **Dual-layer approach:** Catches mistakes at creation time or before commit
+
+### No Significant Gaps Identified
+
+All three "focus areas" from the prompt are handled well:
+- **Eval 2 (user-requested vs. scratch tests):** Clear distinction via "user asked for"
+- **Eval 3 (existing tracked files):** Explicit list + general rule about existing files
+- **Eval 4 (generated-but-committed):** Direct mention of migrations + intent-based reasoning
+

package/skills/file-organization/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill_name": "file-organization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I need to fix a race condition in the websocket handler. I wrote a quick Python script to simulate concurrent connections and reproduce the bug. I also fixed the actual handler. Where does each file go?",
+      "expected_output": "The Python repro script is a working artifact → /temporary/. The websocket handler fix is a deliverable → commit in place.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "User asked me to add unit tests for the payment module. I also created a scratch file to test some regex patterns I needed for the validation logic. Where does each go?",
+      "expected_output": "The unit tests are deliverables (user asked for them) → project tree. The regex scratch file is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I see there's a tests/ directory with existing test files. I also see a file called check-api.sh in the root that I created yesterday to debug an endpoint. What should I do?",
+      "expected_output": "Leave the tests/ directory alone — it's an existing tracked test suite. Move check-api.sh to /temporary/ since it's a debug working artifact.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I'm working on a database migration task. I generated a migration file using the ORM CLI, and I also wrote an analysis.md exploring different indexing strategies. Where do these go?",
+      "expected_output": "The migration file is a deliverable (generated but committed as part of the project) → project tree. The analysis.md is a working artifact → /temporary/.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I created a new React component as requested, plus a debug-render.jsx to test how it renders in isolation. The project already has a __tests__/ folder. Where does everything go?",
+      "expected_output": "The React component is a deliverable → project tree. debug-render.jsx is a working artifact → /temporary/. The __tests__/ folder is existing tracked code — don't touch it.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Before committing, I ran git status and see: modified src/api/users.ts, new file src/api/users.test.ts (user asked for tests), new file output.log, new file temp-check.py. How do I clean this up?",
+      "expected_output": "Commit users.ts (modified existing) and users.test.ts (deliverable). Move output.log and temp-check.py to /temporary/ (working artifacts).",
+      "files": []
+    }
+  ]
+}

package/skills/file-organization/references/gitignore-template.md

@@ -0,0 +1,53 @@
+# .gitignore Template for File Organization Standard
+
+Add this to your `./.gitignore` file to ensure `/temporary/` never gets committed:
+
+```gitignore
+# ============================================
+# Local temporary work (NEVER commit)
+# ============================================
+/temporary/
+```
+
+## Why This Matters
+
+The `/temporary/` folder is where agents and developers place all working files that won't be part of the final codebase:
+- Debug scripts
+- Test experiments
+- Analysis documents
+- Exploration code
+- Generated output
+
+By adding `/temporary/` to `.gitignore`, you ensure:
+1. ✅ No clutter in git history
+2. ✅ Team members only see production code in the repository
+3. ✅ Safe space for experimentation without affecting commits
+4. ✅ Reduced cognitive load when browsing the codebase
+
+## Installation
+
+If you don't have a `.gitignore` file yet:
+1. Create a new file called `.gitignore` in the root of your repository
+2. Add the entry above
+3. Commit it: `git add .gitignore && git commit -m "Add temporary folder to gitignore"`
+
+If you already have a `.gitignore`:
+1. Open it
+2. Add the entry above (preferably in a section labeled "Local temporary work")
+3. Commit the change
+
+## Verification
+
+To verify the setup is correct:
+```bash
+# This should NOT list any files from /temporary/
+git status
+
+# This should show that /temporary/ is ignored
+git check-ignore -v /temporary/something.txt
+```
+
+If `/temporary/` files are appearing in `git status`, double-check that:
+- The `.gitignore` entry is spelled correctly (case-sensitive on Linux/Mac)
+- The file is committed (not just created but not staged)
+- You haven't accidentally added `/temporary/` files with `git add -f`

package/skills/file-organization/references/quick-checklist.md

@@ -0,0 +1,48 @@
+# File Organization Quick Checklist
+
+## At File Creation Time
+
+```
+WHY am I creating this file?
+│
+├─ DELIVERABLE (serves the project / user asked for it)
+│  → Create in project tree
+│
+└─ WORKING ARTIFACT (helps me debug / analyze / explore)
+   → Create in /temporary/
+```
+
+## Before Committing
+
+```bash
+git diff --name-only
+git status
+```
+
+For each file:
+
+| Question | Answer | Action |
+|----------|--------|--------|
+| Did the user's task require this file? | Yes | Commit |
+| Is this an existing file I modified? | Yes | Commit |
+| Did I create this to help myself work? | Yes | Move to /temporary/ |
+| Not sure? | — | Move to /temporary/ (safer) |
+
+## Never Move These to /temporary/
+
+- Existing tracked files you edited
+- Project test suites (`tests/`, `__tests__/`, `spec/`)
+- CI/CD configs (`.github/workflows/`, `Dockerfile`)
+- Lock files (`package-lock.json`, `Cargo.lock`)
+- Migration files
+- Generated code the project commits (protobuf, codegen)
+- Config files (`.eslintrc`, `tsconfig.json`, etc.)
+
+## Common Working Artifacts (Always /temporary/)
+
+- Debug/repro scripts you wrote to investigate
+- Analysis or exploration markdown
+- Scratch files testing an idea
+- Console output or logs you captured
+- Experimental code trying different approaches
+- Notes and drafts that aren't official docs

package/templates/delivery_plan.md

@@ -10,6 +10,7 @@ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
 6b. **§5b Open Questions**: Operational questions that may block active sprint stories
 7. **§6 Completed Sprints**: ONE-LINE summaries of finished sprints (full detail in version history)
 8. **§7 Change Log**: Auto-appended on updates
+9. **§8 Applied Hotfixes**: Ledger of L1 Trivial fixes that bypassed Epic/Story hierarchy (auto-appended by `hotfix_manager.sh ledger`)
 
 Sprint Lifecycle:
 - When a sprint completes: update Sprint Registry row to "Completed",
@@ -186,3 +187,13 @@ DO NOT manually edit the table rows - they are managed by the system.
 | Date | Change | By |
 |------|--------|-----|
 | {YYYY-MM-DD} | Initial creation from Roadmap | Architect |
+
+---
+
+## 8. Applied Hotfixes
+
+> L1 Trivial fixes that bypassed the Epic/Story hierarchy. Auto-appended by `hotfix_manager.sh ledger`.
+
+| Date | Title | Brief Description |
+|------|-------|-------------------|
+| — | — | No hotfixes applied yet |

package/templates/hotfix.md

@@ -47,6 +47,8 @@ Do NOT output these instructions.
 - **Files to Modify**: `{filepath}`
 - **Instructions**: {e.g., "Change the padding-left from 10px to 20px" or "Fix the typo in the error message."}
 
+> **CONSTRAINT**: If this fix requires modifying more than 2 files, STOP immediately and escalate to the Team Lead. The task must be promoted to an Epic/Story.
+
 ---
 
 ## 3. Verification

package/templates/sprint_report.md

@@ -97,7 +97,7 @@ Do NOT output these instructions.
 | **Total QA Bounces** | {N} | across all stories |
 | **Total Architect Bounces** | {N} | across all stories |
 | **Bounce Ratio** | {X}% | (total bounces / total stories) |
-| **Average Correction Tax** | {X}% | (0% = autonomous, 100% = human rewrote everything) |
+| **Average Correction Tax** | {X}% | 🟢 0-5% · 🟡 6-15% · 🔴 16%+ requires process review |
 | **First-Pass Success Rate** | {X}% | stories that passed QA on first try |
 | **Merge Conflicts** | {N} simple, {N} complex | |
 
@@ -107,6 +107,12 @@ Do NOT output these instructions.
 |-------|--------|----------|----------------|---------|------|
 | STORY-{ID} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
 
+### Threshold Alerts
+> Flag any metrics that crossed warning or critical thresholds. If none, write "No threshold alerts."
+
+- {e.g., "STORY-001-05: Correction Tax 10% (🟡) — root cause: test architecture rework due to ESM timer conflict"}
+- {e.g., "STORY-002-03: 2 QA bounces — spec ambiguity in edge case handling"}
+
 ---
 
 ## 4. Lessons Learned