Prepare odd-teaser lane for build-ready state

products/odd-teaser/HISTORY.md

@@ -0,0 +1,87 @@
+# Odd-Teaser — Version History
+
+> Evolution record for the Odd-Teaser PRD.
+
+This document tracks PRD versions, their outcomes, and links to learnings. The lane-root `PRD.md` is the **active, mutable** document. Frozen snapshots live in `attempts/prd-v{VERSION}/PRD.md` when created.
+
+---
+
+## PRD Versions
+
+| Version | Status | Attempts | Key Learning |
+|---------|--------|----------|--------------|
+| **v1.1** | **ACTIVE** | [6593bb53](attempts/prd-v1.1/_runs/6593bb53/) (CLOSED) | Manual categorization UX is hostile; must use LLM-based artifact detection |
+| v1.0 | SUPERSEDED | (graduated from Epoch 4 PoC) | Entry-state must be thinking-first, not artifact editor |
+
+---
+
+## Version Evolution
+
+### v1.1 — Entry-State Posture Correction
+
+**Status:** ACTIVE
+
+**Changes from v1.0:**
+- Conversational thinking precedes artifact commitment
+- Artifact creation is emergent and consent-based
+- Entry-state pressure explicitly removed
+
+**Key Decision:** odd-teaser MUST use LLM-based artifact detection (odd-scribe style) to watch user journaling and surface potential learnings/decisions for user confirmation.
+
+### v1.0 — Initial Lane Instantiation
+
+**Status:** SUPERSEDED by v1.1
+
+**Origin:** Graduated from Epoch 4 guiding artifact (`klappy://docs/guiding-artifacts/epoch-4/klappy-dev-poc-prd`)
+
+**Core Philosophy Established:**
+- Single-session epistemic experience
+- Klappy.dev must always be easier to leave than to continue
+- Product succeeds even if user never returns
+
+---
+
+## Learnings by Version
+
+### v1.1 Learnings
+
+- [Run 6593bb53 LEARNINGS.md](attempts/prd-v1.1/_runs/6593bb53/LEARNINGS.md)
+- [Run 6593bb53 EVIDENCE.md](attempts/prd-v1.1/_runs/6593bb53/EVIDENCE.md)
+
+**What we learned:**
+
+1. **Manual categorization UX is hostile** — If users must click buttons to categorize their own writing, they abandon the system. odd-teaser should detect artifact scents automatically like odd-scribe.
+
+2. **Ritual complexity is severe** — The attempt workflow requires so many manual steps that even with AI assistance and clear documentation, attempts fail due to process overhead, not implementation quality.
+
+3. **Scribe needs lane-awareness** — Global odd/ledger/ namespace was polluted with lane-specific learnings.
+
+4. **Entry-state must communicate safety** — "Nothing is committed until you say so" is the critical message.
+
+---
+
+## Key Decisions
+
+| ID | Decision | Status |
+|----|----------|--------|
+| dec-20260131-0001 | odd-teaser MUST use LLM-based artifact detection | ACCEPTED |
+
+---
+
+## Version Transition Rules
+
+1. **PRD mutations** happen in lane-root `PRD.md` only
+2. **Frozen snapshots** are created in attempt folders at kickoff (when needed)
+3. **Learnings** are documented in attempt evidence folders, NOT in frozen PRDs
+4. **New versions** increment when requirements change significantly
+5. **Closing a version** = marking status as SUPERSEDED in this file
+
+---
+
+## See Also
+
+- [PRD.md](PRD.md) — Current active PRD
+- [README.md](README.md) — Lane overview
+- [KICKOFF.md](KICKOFF.md) — How to start an attempt
+- [LEDGER.md](LEDGER.md) — Product-level decisions and locks
+- [behavior.md](behavior.md) — LLM behavior enforcement

products/odd-teaser/KICKOFF.md

@@ -0,0 +1,253 @@
+# Odd-Teaser — Attempt Kickoff
+
+You are starting an attempt in the **odd-teaser** lane.
+
+---
+
+## STOP — READ THIS FIRST
+
+**The #1 cause of failed attempts is writing outside the attempt folder.**
+
+This is not a suggestion. This is not flexible. This is the rule that will fail your attempt regardless of how good your code is.
+
+```
++-----------------------------------------------------------------------+
+|                     YOUR SANDBOX (Agent Authority)                     |
+|                                                                        |
+|   products/odd-teaser/attempts/v<VERSION>/attempt-NNN/                 |
+|                                                                        |
+|   You can write ANYTHING here. Go wild.                                |
+|   - ATTEMPT.md, META.json                                              |
+|   - src/           <- proposed implementation code                     |
+|   - evidence/      <- proof it works (screenshots, logs, exports)      |
+|                                                                        |
++------------------------------------------------------------------------+
+|                     FORBIDDEN ZONE (Human Authority)                   |
+|                                                                        |
+|   products/odd-teaser/src/           <- NEVER (human promotes)         |
+|   products/odd-teaser/dist/          <- NEVER (build output)           |
+|   products/odd-teaser/PRD.md         <- NEVER (propose changes only)   |
+|   products/odd-teaser/behavior.md    <- NEVER (propose changes only)   |
+|   public/                            <- NEVER (deployment is human)    |
+|                                                                        |
+|   These paths require HUMAN promotion. Not your job.                   |
+|                                                                        |
++------------------------------------------------------------------------+
+```
+
+---
+
+## AUTHORITY BOUNDARIES — What You CANNOT Do
+
+| Action | Why It Fails Your Attempt |
+|--------|---------------------------|
+| Write to lane `src/` | Lane source is human-promoted, not agent-deployed |
+| Write to `public/` | Production deployment requires human review |
+| Claim CHAMPION status | Agent stops at CLOSED; human elevates to CHAMPION |
+| Update lane PRD | Propose changes in ATTEMPT.md; human applies |
+| Deploy to Cloudflare | Even preview deploys require human action |
+| Modify behavior.md | Propose changes; human reviews |
+
+**"AI is an accelerator, not an authority."**
+
+---
+
+## PRE-FLIGHT CHECKLIST
+
+Before you write a single line of code, verify you understand:
+
+- [ ] My attempt folder is: `products/odd-teaser/attempts/v<VERSION>/attempt-NNN/`
+- [ ] ALL my file writes will be inside that folder
+- [ ] If I need to propose UI code, I write to `attempt-NNN/src/`
+- [ ] Screenshots and evidence go to `attempt-NNN/evidence/`
+- [ ] I will NOT update lane `src/` — that's a human promotion
+- [ ] I will NOT claim CHAMPION — I stop at CLOSED
+- [ ] If the PRD seems impossible, I FAIL early and document why
+
+---
+
+## Step 1: Find Active Version
+
+Check `HISTORY.md` — the Versions table shows which version is **Active**.
+
+Note the active version (e.g., `v1.1`). This is your target.
+
+---
+
+## Step 2: Read Context
+
+Read these files in order:
+
+1. `README.md` — Lane overview
+2. `PRD.md` — The authoritative PRD (currently v1.1)
+3. `behavior.md` — LLM behavior contract
+4. `HISTORY.md` — Prior attempts and learnings
+5. `LEDGER.md` — Product-level decisions and locks
+
+---
+
+## Step 3: Review Prior Art
+
+Read the learnings from previous attempts:
+
+| Path | What To Learn |
+|------|---------------|
+| `attempts/prd-v1.1/_runs/*/LEARNINGS.md` | Entry-state posture lessons |
+
+If you see patterns in past failures that relate to your task, **stop and plan around them**.
+
+---
+
+## Step 4: Create Attempt Folder
+
+Create: `attempts/v<VERSION>/attempt-NNN/`
+
+Where NNN is the next number (check existing folders).
+
+### Required Structure
+
+```
+attempt-NNN/
++-- ATTEMPT.md              # Closure record (status, outcome, learnings)
++-- META.json               # Machine-readable metadata
++-- src/                    # Proposed implementation
+|   +-- components/         # UI components
+|   +-- styles/             # Styling
+|   +-- index.html          # Entry point
++-- evidence/               # Proof of work
+    +-- screenshots/        # Visual evidence
+    +-- export-sample.md    # Example artifact export
+    +-- *.md                # Verification evidence
+```
+
+---
+
+## Step 5: Execute (Inside Your Sandbox)
+
+Follow the PRD's Definition of Done exactly.
+
+### Key Requirements from PRD
+
+1. **Entry-state**: Thinking-first, not artifact editor
+2. **Artifact types**: Learnings, Decisions, Overrides
+3. **Export**: One-click, Markdown, local-only
+4. **Non-goals**: No auth, no persistence, no teaching, no navigation
+
+### Testing Your Implementation
+
+```bash
+# WRONG: This violates containment
+cp -r attempt-NNN/src/* products/odd-teaser/src/
+
+# RIGHT: Test locally from your sandbox
+npx serve attempt-NNN/src/
+```
+
+---
+
+## Step 6: Close (NOT Champion)
+
+Update `ATTEMPT.md` with:
+
+- **Status**: CLOSED (not CHAMPION — that's not your call)
+- Outcome summary
+- Evidence produced
+- Self-audit results
+- Learnings
+
+**You do NOT:**
+- Update `HISTORY.md` (human does this)
+- Deploy to production (human does this)
+- Mark status as CHAMPION (human does this)
+
+---
+
+## Product-Specific Constraints
+
+### Core Philosophy
+
+This is NOT a documentation site. This is NOT a teaching tool.
+
+The product exists for **epistemic externalization and exit**.
+
+**Klappy.dev must always be easier to leave than to continue.**
+
+### Success Definition
+
+A first-time visitor leaves after one session having:
+
+1. Externalized at least one epistemic artifact
+2. Noticed a missing habit in their own workflow
+3. Taken something with them (export)
+
+The product succeeds even if the user never returns.
+
+### Forbidden Features
+
+If a feature increases time-on-site without increasing artifact creation, it is invalid.
+
+- No engagement optimization
+- No retention features
+- No navigation trees
+- No menus beyond artifact visibility
+
+---
+
+## Common Violations (Don't Be This Agent)
+
+### Violation 1: Building a documentation browser
+
+```diff
+- "Let me add a sidebar to browse ODD concepts"     <- VIOLATION
++ Single-page, artifact-focused experience          <- CORRECT
+```
+
+**Why it fails**: PRD explicitly forbids navigation and teaching.
+
+### Violation 2: Adding engagement features
+
+```diff
+- "Let me add a progress indicator to encourage completion"  <- VIOLATION
++ Exit is the goal, not completion                          <- CORRECT
+```
+
+**Why it fails**: Engagement optimization is a non-goal.
+
+### Violation 3: Persisting user state
+
+```diff
+- "Let me save artifacts to localStorage for return visits"  <- VIOLATION
++ Export is the exit ramp; no persistence                   <- CORRECT
+```
+
+**Why it fails**: PRD explicitly forbids identity persistence.
+
+---
+
+## If PRD Seems Problematic
+
+**Don't bend rules to make it work. Don't steer a miss.**
+
+1. STOP immediately
+2. Document the issue in `ATTEMPT.md`
+3. Mark attempt as FAILED with clear explanation
+4. Propose what a new PRD version should address
+
+A FAILED attempt with clear learnings is more valuable than a "success" that violates constraints.
+
+---
+
+## Final Reminder
+
+```
++------------------------------------------------------------+
+|                                                             |
+|   Your world is:                                            |
+|   products/odd-teaser/attempts/v<VERSION>/attempt-NNN/      |
+|                                                             |
+|   Everything else is someone else's.                        |
+|                                                             |
+|   "AI is an accelerator, not an authority."                 |
+|                                                             |
++------------------------------------------------------------+
+```