@hopla/claude-setup 1.3.2 → 1.3.3

package/files/commands/guides/data-audit.md

@@ -0,0 +1,58 @@
+# Guide: Data Audit and Value Semantics
+
+Use this guide when a feature reads from, calculates with, or references existing data or code patterns. Applies during planning (full audit) and execution (verification of documented findings).
+
+---
+
+## 1. Data Model Audit
+
+When a feature reads from existing tables or APIs, audit ALL field variants — not just the happy path:
+
+- **Nullability:** Can values be null? What does null mean in context? (e.g., null might indicate a formula, a default, or a computed value — not simply "empty")
+- **Multiple representations:** Are there alternative forms of the same concept? (e.g., direct value vs expression vs derived value)
+- **Resolution chain:** What is the complete lookup chain? (e.g., primary source → fallback → default)
+
+Document every variant found: what each means and when it occurs.
+
+---
+
+## 2. Value Semantics Verification
+
+When a feature involves calculations with stored amounts, **do not assume** — verify by reading the display/formatter code in existing modules that already consume this data.
+
+Check:
+- Are values signed or unsigned?
+- Are they absolute amounts, deltas, or percentages?
+- What is the sign convention? A field named "amount" could be positive-means-add **or** positive-means-subtract depending on domain convention.
+
+**How to verify:** Find a module that already displays or formats these values. Read it completely. Use it as ground truth for the formula.
+
+---
+
+## 3. Working Reference Pattern
+
+When using a framework-specific pattern (custom editors, middleware, event handlers, streaming, etc.):
+
+- Do not list a file as "reference" without reading it
+- Find a **proven working implementation** of the EXACT pattern needed
+- Read it completely and extract: API calls, prop types, data flow, lifecycle assumptions
+- Document this extracted pattern in the plan's task details — not as a vague "Pattern: see file X"
+
+---
+
+## 4. Derived Value Propagation
+
+If any value is calculated from other fields, specify:
+- The exact formula including how stored values are interpreted (sign, units, semantics)
+- How derived values propagate when inputs change (event system, reactivity, polling, etc.)
+
+---
+
+## Responsibilities by Role
+
+| Role | Responsibility |
+|------|---------------|
+| **Planner** | Runs the full audit. Documents all findings in the plan's **Context References** and **Gotchas** fields. |
+| **Executor** | Verifies that the planner's findings still hold — confirms files exist, patterns match, fields haven't changed. Does NOT re-audit from scratch. |
+
+If the executor finds a discrepancy between the plan's documented findings and reality, they stop and file a Blocker Report (see `hopla-execute.md`).

package/files/commands/hopla-execute.md

@@ -15,6 +15,31 @@ Read in this order:
 
 Do not start implementing until you have read everything above.
 
+### Verification Checkpoints (before writing code)
+
+Verify that the plan's documented assumptions still hold. **You are not re-auditing from scratch** — the planner already did the full audit and documented findings in Context References and Gotchas. Your job is to confirm each finding is still accurate:
+
+- **Data models:** Read the referenced API route or schema. Confirm the field variants the planner documented (null cases, alternative representations, resolution chain) still match the actual code.
+- **Value semantics:** If the plan documents a formula, confirm the sign/unit convention still matches the actual display/formatter code.
+- **Reference patterns:** Read each Pattern file completely. Confirm the specific API calls, types, and data flow still match what the plan describes.
+
+See `.agents/guides/data-audit.md` for detailed criteria on what to check.
+
+If a discrepancy is found, stop immediately and file a Blocker Report below. You may continue with tasks that are not blocked by the discrepancy.
+
+#### Blocker Report
+
+Use when a plan assumption does not match reality:
+
+```
+## Blocker Report
+
+- **Blocked task:** [Task number and name]
+- **Failed assumption:** [What the plan said]
+- **Actual state:** [What you found — include a code snippet or data example]
+- **Recommendation:** [Replan X | Fix Y | Proceed with caution because Z]
+```
+
 ## Step 2: Verify Git Branch
 
 ```bash
@@ -54,11 +79,12 @@ Work through each task in the plan sequentially. For each task:
 5. **Report completion** with a brief status: what was done, what was skipped, any decision made
 6. **Do not proceed** to the next task if the current one fails validation
 
-**Trust but Verify — pause and report if:**
-- A file referenced in the plan doesn't exist
-- The actual pattern in the code differs from what the plan assumed
+**Git strategy:** Do not commit after individual tasks. Keep all changes staged but uncommitted until the full plan passes validation (Step 5). This allows a clean revert if later tasks fail.
+
+**Pause and report if, during implementation:**
 - A task is ambiguous or has multiple valid implementations
 - Something unexpected is discovered that could affect subsequent tasks
+- The plan's structure or ordering doesn't match conventions used elsewhere in the project
 
 Do not improvise silently. When in doubt, stop and ask.
 

package/files/commands/hopla-plan-feature.md

@@ -46,6 +46,12 @@ Use the Grep tool to find relevant files (pattern: relevant keyword, case-insens
 
 Read the key files in their entirety — not just the parts that seem relevant.
 
+### Data audit (required for features that consume existing data)
+
+Follow the full checklist in `.agents/guides/data-audit.md`.
+
+**Your responsibility as planner:** Run the complete audit and document ALL findings in the plan's **Context References** and **Gotchas** fields. The executing agent must be able to verify your findings without re-auditing — they should only confirm that what you documented still holds.
+
 ## Phase 4: Design the Approach
 
 Based on research, define:
@@ -54,6 +60,7 @@ Based on research, define:
 - What the data flow looks like end-to-end
 - Any risks, edge cases, or gotchas to flag
 - What tests are needed
+- **Derived/computed values:** If any value is calculated from other fields, specify the exact formula including how stored values are interpreted (sign, units, semantics), AND how derived values propagate when inputs change (event system, reactivity, polling, etc.)
 
 ## Phase 5: Generate the Plan
 
@@ -127,6 +134,8 @@ Before saving the draft, review the plan against these criteria:
 - [ ] Validation Checklist has **exact commands** from `CLAUDE.md` or `package.json` (not vague "run lint")
 - [ ] The plan is complete enough that another agent can execute it without this conversation
 - [ ] No ambiguous requirements left unresolved
+- [ ] **Data audit complete:** All data sources audited per `.agents/guides/data-audit.md`, with all findings (null cases, value semantics, derived value propagation) documented in Context References and Gotchas
+- [ ] **Working references specified:** Every framework-specific pattern references a proven working implementation with extracted API calls, prop types, and data flow — not just "see file X"
 
 ## Phase 7: Save Draft and Enter Review Loop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hopla/claude-setup",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Hopla team agentic coding system for Claude Code",
   "type": "module",
   "bin": {