@blxzer/pactile 0.5.0

package/dist/templates/markdown/spec/guides/code-reuse-thinking-guide.md.txt

@@ -0,0 +1,174 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+### Pattern 4: Repeated Payload Field Extraction
+
+**Bad**: Multiple consumers cast the same JSON/event fields locally:
+
+```typescript
+const description = (ev as { description?: string }).description;
+const context = (ev as { context?: ContextEntry[] }).context;
+```
+
+This is duplicated contract logic even when the code is only two lines. Each
+consumer now has its own definition of what a valid payload means.
+
+**Good**: Put the decoder, type guard, or projection next to the data owner:
+
+```typescript
+if (isThreadEvent(ev)) {
+  renderThreadEvent(ev);
+}
+```
+
+**Rule**: If the same untyped payload field is read in 2+ places, create a
+shared type guard / normalizer / projection before adding a third reader.
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+### Reducers Should Use Exhaustive Structure
+
+When state is derived from action-like values (`action`, `kind`, `status`,
+`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
+
+```typescript
+// BAD - action-specific state transitions are hard to audit
+if (action === "opened") { ... }
+else if (action === "comment") { ... }
+else if (action === "status") { ... }
+
+// GOOD - one reducer owns the transition table
+switch (event.action) {
+  case "opened":
+    ...
+    return;
+  case "comment":
+    ...
+    return;
+}
+```
+
+This matters when the event log is the source of truth. A reducer is the
+documented replay model; display code and commands should not duplicate pieces
+of that replay model.
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] No repeated untyped payload field extraction outside a shared decoder
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure
+- [ ] Reducer/action transitions live in one reducer or command dispatcher
+
+---
+
+## Gotcha: Python if/elif/else Exhaustive Check
+
+**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., a hook event name), existing if/elif/else chains silently fall through to `else` with wrong defaults.
+
+**Symptom**: New value works partially — some methods return the default branch instead of the new value's specific behavior. No error is raised.
+
+**Example** (`cli_adapter.py`):
+```python
+# BAD: "on_session_end" falls through to else, returns session-start defaults
+@property
+def hook_kind(self) -> str:
+    if self.event == "on_session_start":
+        return "session-start"
+    else:
+        return "session-start"  # on_session_end silently gets "session-start"!
+
+# GOOD: explicit branch for every value
+@property
+def hook_kind(self) -> str:
+    if self.event == "on_session_start":
+        return "session-start"
+    elif self.event == "on_session_end":
+        return "session-end"
+    else:
+        return "session-start"
+```
+
+**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.

package/dist/templates/markdown/spec/guides/cross-layer-thinking-guide.md.txt

@@ -0,0 +1,162 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: Think through data flow across layers before implementing.
+
+---
+
+## The Problem
+
+**Most bugs happen at layer boundaries**, not within layers.
+
+Common cross-layer bugs:
+
+- API returns format A, frontend expects format B
+- Database stores X, service transforms to Y, but loses data
+- Multiple layers implement the same logic differently
+
+---
+
+## Before Implementing Cross-Layer Features
+
+### Step 1: Map the Data Flow
+
+Draw out how data moves:
+
+```
+Source → Transform → Store → Retrieve → Transform → Display
+```
+
+For each arrow, ask:
+
+- What format is the data in?
+- What could go wrong?
+- Who is responsible for validation?
+
+### Step 2: Identify Boundaries
+
+| Boundary              | Common Issues                     |
+| --------------------- | --------------------------------- |
+| API ↔ Service         | Type mismatches, missing fields   |
+| Service ↔ Database    | Format conversions, null handling |
+| Backend ↔ Frontend    | Serialization, date formats       |
+| Component ↔ Component | Props shape changes               |
+
+### Step 3: Define Contracts
+
+For each boundary:
+
+- What is the exact input format?
+- What is the exact output format?
+- What errors can occur?
+
+---
+
+## Common Cross-Layer Mistakes
+
+### Mistake 1: Implicit Format Assumptions
+
+**Bad**: Assuming date format without checking
+
+**Good**: Explicit format conversion at boundaries
+
+### Mistake 2: Scattered Validation
+
+**Bad**: Validating the same thing in multiple layers
+
+**Good**: Validate once at the entry point
+
+### Mistake 3: Leaky Abstractions
+
+**Bad**: Component knows about database schema
+
+**Good**: Each layer only knows its neighbors
+
+### Mistake 4: Every Consumer Parses The Same Payload
+
+**Bad**: A command reads JSONL events and casts fields inline:
+
+```typescript
+const thread = (ev as { thread?: string }).thread;
+const labels = (ev as { labels?: string[] }).labels;
+```
+
+This looks local, but it means every consumer owns a private version of the
+event contract. The next field change will update one command and miss another.
+
+**Good**: Decode once at the event boundary, then export typed projections:
+
+```typescript
+if (!isThreadEvent(ev)) return false;
+return ev.thread === filter.thread;
+```
+
+**Rule**: For append-only logs, JSON streams, RPC payloads, or config files,
+create one owner for:
+
+- event / payload type definitions
+- type guards and normalization from `unknown`
+- metadata projections used by UI commands
+- reducers that replay state from the source of truth
+
+Rendering code may format fields, but it must not redefine the payload contract.
+
+---
+
+## Checklist for Cross-Layer Features
+
+Before implementation:
+
+- [ ] Mapped the complete data flow
+- [ ] Identified all layer boundaries
+- [ ] Defined format at each boundary
+- [ ] Decided where validation happens
+
+After implementation:
+
+- [ ] Tested with edge cases (null, empty, invalid)
+- [ ] Verified error handling at each boundary
+- [ ] Checked data survives round-trip
+- [ ] Checked that consumers import shared decoders / projections instead of
+      casting payload fields locally
+- [ ] Checked that derived state points back to the source event identifier
+      (`seq`, `id`, `version`) instead of inventing a second cursor
+
+---
+
+## When to Create Flow Documentation
+
+Create detailed flow docs when:
+
+- Feature spans 3+ layers
+- Multiple teams are involved
+- Data format is complex
+- Feature has caused bugs before
+
+---
+
+## Event Log / Projection Boundary
+
+Append-only logs are cross-layer contracts. A single event travels through:
+
+```
+CLI input → event writer → events.jsonl → reader → filter → reducer → display
+```
+
+### Checklist: After Adding A New Event Kind Or Field
+
+- [ ] Add the event kind to the central event taxonomy
+- [ ] Add a typed event variant or type guard at the event layer
+- [ ] Add normalization helpers for array/object fields that come from
+      user input or JSON
+- [ ] Keep `seq` / `id` assignment in the event writer only
+- [ ] Make filters and reducers consume the typed event guard, not local casts
+- [ ] Make display code consume reducer output or typed events, not raw JSON
+- [ ] Add at least one regression that proves history replay and live filtering
+      use the same filter model
+
+**Real-world example**: Thread channels added `kind: "thread"`, `description`,
+`context`, labels, and `lastSeq`. The first implementation replayed thread
+state correctly, but several commands still re-parsed event payload fields with
+local casts. The fix was to make the core event layer own `ThreadChannelEvent`
+and `isThreadEvent`, make `reduceChannelMetadata` the only channel metadata
+projection, and make `reduceThreads` the only thread replay reducer.