leancraft 0.1.0

package/.leancraft/config.json

@@ -0,0 +1,357 @@
+{
+  "version": "1.0.0",
+  "name": "leancraft",
+  "description": "Doc-first verified agency — the registry is the contract. Agent MUST read this first. Lock enforces ownership.",
+  "locked": false,
+  "ownership": {
+    "human": [
+      "human/**"
+    ],
+    "agent": [
+      "agent/**"
+    ],
+    "joint": [
+      "joint/**"
+    ],
+    "denyAgentWrite": [
+      "human/**"
+    ],
+    "allowAgentWrite": [
+      "agent/**",
+      "joint/**"
+    ],
+    "humanOwners": "@human-owners"
+  },
+  "budget": {
+    "maxCostUSD": 5,
+    "maxToolCalls": 25,
+    "maxWallClockMinutes": 30,
+    "sandbox": "gvisor",
+    "network": "deny-all",
+    "allowlist": [
+      "registry.npmjs.org",
+      "registry.yarnpkg.com",
+      "pypi.org"
+    ],
+    "forbiddenEnv": [
+      ".env",
+      "DATABASE_URL",
+      "AWS_*",
+      "GITHUB_TOKEN"
+    ],
+    "githubTokenScope": "read-only"
+  },
+  "sprintGates": {
+    "prototypeRequires": "human/definition/intent.md",
+    "testRequires": "joint/test-report.md",
+    "minRealUserNotes": 5
+  },
+  "docRegistry": {
+    "discovery": {
+      "00-index.md": {
+        "required": true,
+        "description": "Reading order, conventions, status legend, how agents should use docs",
+        "template": "templates/discovery/00-index.md",
+        "sections": [
+          "reading-order",
+          "conventions",
+          "status-legend",
+          "agent-usage"
+        ]
+      },
+      "00-overview.md": {
+        "required": true,
+        "description": "Elevator pitch, parent+brands shape, tech stack, cost ceiling",
+        "template": "templates/discovery/00-overview.md",
+        "sections": [
+          "elevator-pitch",
+          "brand-shape",
+          "tech-stack",
+          "cost-ceiling"
+        ]
+      },
+      "01-vision.md": {
+        "required": true,
+        "description": "North star, 10x-vs-parity, 3-year vision",
+        "template": "templates/discovery/01-vision.md",
+        "sections": [
+          "north-star",
+          "10x-vs-parity",
+          "3-year-vision"
+        ]
+      },
+      "02-research.md": {
+        "required": true,
+        "description": "12 pain themes with real quotes",
+        "template": "templates/discovery/02-research.md",
+        "sections": [
+          "pain-themes",
+          "sources"
+        ],
+        "rules": {
+          "minPainThemes": 12,
+          "minSources": 12,
+          "requireQuoteAndURL": true
+        }
+      },
+      "03-competitive.md": {
+        "required": true,
+        "description": "Competitor teardown + pricing + wedges",
+        "template": "templates/discovery/03-competitive.md",
+        "sections": [
+          "competitors",
+          "pricing-table",
+          "wedges"
+        ],
+        "rules": {
+          "minCompetitors": 9,
+          "requirePricingWithCurrency": true,
+          "minWedges": 5
+        }
+      },
+      "04-personas.md": {
+        "required": true,
+        "description": "5 personas + affinity map",
+        "template": "templates/discovery/04-personas.md",
+        "sections": [
+          "personas",
+          "affinity-map"
+        ],
+        "rules": {
+          "minPersonas": 5,
+          "requireFields": [
+            "goals",
+            "pains",
+            "jtbd"
+          ]
+        }
+      },
+      "05-jtbd.md": {
+        "required": true,
+        "description": "JTBD + empathy maps + pain matrix",
+        "template": "templates/discovery/05-jtbd.md",
+        "sections": [
+          "jtbd-statements",
+          "empathy-maps",
+          "pain-matrix"
+        ]
+      },
+      "06-prd.md": {
+        "required": true,
+        "description": "Goals, non-goals, flows, FRs, NFRs + lean overview (metrics, assumptions, RACI, PESTEL, 4 Whys, timeline, legal)",
+        "template": "templates/discovery/06-prd.md",
+        "sections": [
+          "goals",
+          "non-goals",
+          "success-metrics",
+          "assumptions",
+          "user-flows",
+          "functional-reqs",
+          "nfrs",
+          "stakeholders",
+          "raci",
+          "pestel",
+          "4-whys",
+          "timeline",
+          "legal",
+          "risks"
+        ],
+        "rules": {
+          "minUserFlows": 3,
+          "minFunctionalReqs": 10
+        }
+      }
+    },
+    "definition": {
+      "intent.md": {
+        "required": true,
+        "description": "Global invariants + oracles (executable spec)",
+        "template": "templates/definition/intent.md",
+        "sections": [
+          "intent",
+          "invariants",
+          "oracles",
+          "non-goals"
+        ],
+        "rules": {
+          "minInvariants": 3,
+          "minOracles": 2
+        }
+      },
+      "system.md": {
+        "required": true,
+        "description": "Architecture, stack, decisions, integrations, deployment",
+        "template": "templates/definition/system.md",
+        "sections": [
+          "stack",
+          "architecture",
+          "decisions",
+          "integrations",
+          "deployment",
+          "data-model"
+        ]
+      },
+      "guardrails.md": {
+        "required": true,
+        "description": "Security, perf, a11y, i18n, legal rules",
+        "template": "templates/definition/guardrails.md",
+        "sections": [
+          "security",
+          "performance",
+          "a11y",
+          "i18n",
+          "legal"
+        ]
+      },
+      "features/*.md": {
+        "required": false,
+        "description": "1 per user flow from 06-prd.md, ephemeral",
+        "template": "templates/definition/feature.md",
+        "sections": [
+          "intent",
+          "invariants",
+          "oracles",
+          "acceptance"
+        ],
+        "naming": "NNN-kebab-case.md (e.g., 042-pdf-export.md)"
+      }
+    },
+    "sprint": {
+      "map.md": {
+        "required": false,
+        "description": "Day 1: HMW, target, map (Design Sprint)",
+        "template": "templates/sprint/map.md"
+      },
+      "sketches.md": {
+        "required": false,
+        "description": "Day 2: Crazy 8s + decision"
+      },
+      "test-report.md": {
+        "required": false,
+        "description": "Day 3: 5 real user notes (joint)",
+        "rules": {
+          "minRealUserNotes": 5
+        }
+      }
+    },
+    "conditional": {
+      "07-data.md": {
+        "if": "product has persistence",
+        "description": "Storage, schema, PII, retention"
+      },
+      "08-agents.md": {
+        "if": "product has agents/bots",
+        "description": "Bot definitions, permissions, HITL"
+      },
+      "09-skills.md": {
+        "if": "product has skills/extensions",
+        "description": "Skill format, dos/donts"
+      },
+      "10-ux.md": {
+        "if": "product has UI",
+        "description": "Wireframes-as-text, IA, a11y"
+      },
+      "11-design-system.md": {
+        "if": "product has UI",
+        "description": "Tokens, components, motion"
+      }
+    }
+  },
+  "researchMap": {
+    "02-research.md": {
+      "requires": [
+        {
+          "type": "web_search",
+          "examples": [
+            "tavily_search",
+            "exa_search",
+            "brave_search",
+            "WebSearch",
+            "web_search"
+          ],
+          "purpose": "find URLs with real quotes"
+        },
+        {
+          "type": "web_fetch",
+          "examples": [
+            "firecrawl",
+            "exa_fetch",
+            "WebFetch",
+            "web_fetch",
+            "fetch"
+          ],
+          "purpose": "fetch page as markdown to extract verbatim quote"
+        }
+      ],
+      "queries": [
+        "{idea} pain",
+        "{idea} reddit",
+        "{idea} alternative",
+        "{idea} complaint"
+      ],
+      "requireURLs": true,
+      "fallback": "If no tool of type web_search/web_fetch exists, STOP. Do NOT invent. Write to agent/status.md: 'BLOCKED: No web_search available — human must provide 02-research.md or connect a search connector (Tavily/Exa/Brave)' and append to joint/decisions.log.md. Ask human to paste research or enable a connector."
+    },
+    "03-competitive.md": {
+      "requires": [
+        {
+          "type": "web_search",
+          "examples": [
+            "tavily_search",
+            "exa_search",
+            "brave_search",
+            "WebSearch"
+          ],
+          "purpose": "find competitors + pricing pages"
+        }
+      ],
+      "requirePricing": true,
+      "fallback": "If no web_search, STOP. Write to agent/status.md and ask human. Do NOT invent pricing."
+    },
+    "04-personas.md": {
+      "derivedFrom": "02-research.md",
+      "noNewSearch": true,
+      "requires": []
+    },
+    "05-jtbd.md": {
+      "derivedFrom": [
+        "02-research.md",
+        "03-competitive.md",
+        "04-personas.md"
+      ],
+      "requires": []
+    },
+    "06-prd.md": {
+      "derivedFrom": [
+        "02-research.md",
+        "04-personas.md",
+        "05-jtbd.md"
+      ],
+      "requires": []
+    },
+    "intent.md": {
+      "derivedFrom": [
+        "06-prd.md"
+      ],
+      "requires": []
+    },
+    "system.md": {
+      "derivedFrom": [
+        "06-prd.md",
+        "02-research.md"
+      ],
+      "requires": []
+    }
+  },
+  "validation": {
+    "command": "npm run leancraft:validate",
+    "blockLockIfFail": true,
+    "checks": [
+      "required-docs",
+      "required-sections",
+      "min-counts",
+      "requireURLs",
+      "no-placeholders"
+    ]
+  }
+}

package/.leancraft/human/definition/features/042-example-feature.md

@@ -0,0 +1,32 @@
+# Feature — 042-example-feature
+
+> Status: DRAFT — 1 per flow from 06-prd.md. Ephemeral, delete when shipped. Copy this template per feature.
+
+## Intent
+
+[1 paragraph from 06-prd.md Flow N]
+
+## Invariants (scoped)
+
+- **I1:** [feature-specific]
+- **I2:**
+
+## Oracles
+
+- **O1:** Property test:
+- **O2:** e2e:
+
+## Acceptance
+
+- [ ] Given ... When ... Then ...
+- [ ] Axe passes
+- [ ] Perf <2s
+
+## Source Trace
+
+- FR-05, Persona: Solo Sree
+
+## Validation
+
+- [ ] Invariants with Check
+- [ ] Source trace

package/.leancraft/human/definition/guardrails.md

@@ -0,0 +1,37 @@
+# Guardrails — Security, Perf, A11y, i18n
+
+> Status: DRAFT — Agent MUST obey. CI enforces.
+
+## Security
+
+- CWE-89 SQLi: Never string-concat SQL, use parameterized / scopedQuery()
+- CWE-79 XSS: Never innerHTML
+- Secrets: Never commit .env, use wrangler secret
+- AuthZ: Every query scoped by userId + brandId
+- Checks: semgrep, codeql
+
+## Performance
+
+- LCP <2.5s, no N+1, paginate >100
+- Checks: autocannon, lighthouse
+
+## A11y
+
+- WCAG AA, axe-core must pass
+- No color-only, ARIA labels required
+
+## i18n
+
+- No hardcoded strings, use t() keys
+
+## Legal / Privacy (from 06-prd Legal)
+
+- Data / PII: (from 07-data.md if exists)
+- IP / License:
+- Regulatory: (GDPR, etc.)
+- Checks: legal review
+
+## Validation
+
+- [ ] 5 sections present
+- [ ] Each has Check command

package/.leancraft/human/definition/intent.md

@@ -0,0 +1,31 @@
+# Intent — Global Executable Spec
+
+> Status: DRAFT — Distilled from 06-prd.md. Agent codes ONLY against this.
+
+## Intent
+
+[TODO: 1 paragraph, distilled from 06-prd.md]
+
+## Invariants (≥3, machine-checkable)
+
+- **I1:** [e.g., totalChargesInScope == SUM(lineItems where scopeId==X)] — Check: `npm run test:invariants`
+- **I2:** [e.g., PDF must be WCAG AA] — Check: `axe-core`
+- **I3:** [e.g., Never string-concat SQL] — Check: `semgrep`
+
+## Oracles (≥2)
+
+- **O1:** Property test — `fast-check` 500 random inputs
+- **O2:** Security — CodeQL/Semgrep passes
+
+## Non-Goals
+
+- Not:
+
+## Source Trace
+
+- FR-01, FR-05; Success Metric: Activation; Assumption: [from 06-prd.md]; Persona P1
+
+## Validation
+
+- [ ] ≥3 invariants with Check
+- [ ] ≥2 oracles with tool

package/.leancraft/human/definition/system.md

@@ -0,0 +1,48 @@
+# System — Architecture & Decisions
+
+> Status: DRAFT
+
+## Stack (pinned)
+
+- Frontend:
+- Backend:
+- DB:
+- Infra:
+
+## Architecture
+
+```
+[TODO: diagram]
+client → worker → D1
+```
+
+## Decisions
+
+| Decision | Chosen | Rejected | Why |
+|---|---|---|---|
+|  |  |  |  |
+
+## Integrations / Dependencies (from 06-prd Stakeholders)
+
+| System | API / Host | Why | Allowlist |
+|---|---|---|---|
+| [e.g., Stripe] | api.stripe.com | Payments | → config allowlist |
+
+## Deployment / Infra (light)
+
+- Hosting:
+- Env: dev / staging / prod
+- CI: GitHub Actions
+
+## Data Model
+
+- Tables:
+- PII handling: (links to discovery/07-data.md if exists)
+- Agents: (links to 08-agents.md if exists)
+- UX: (links to 10-ux.md if exists)
+
+## Validation
+
+- [ ] Pinned versions
+- [ ] Diagram + decisions with why
+- [ ] Integrations + Deployment present (overview, 3 lines)

package/.leancraft/human/discovery/00-index.md

@@ -0,0 +1,40 @@
+# 00 — Index — Reading Order & Conventions
+
+> Status: DRAFT — Run `npm run leancraft:validate` before Lock
+
+## Reading Order
+
+1. `00-overview.md` → elevator pitch + stack + cost ceiling
+2. `01-vision.md` → north star, 10x-vs-parity, 3-year
+3. `02-research.md` → P1-P12 pain themes (12 real quotes + URLs)
+4. `03-competitive.md` → 9+ competitors + pricing + wedges
+5. `04-personas.md` → 5 personas + affinity map
+6. `05-jtbd.md` → JTBD + empathy maps + pain matrix
+7. `06-prd.md` → goals, non-goals, flows, FRs, NFRs
+8. `../definition/intent.md` → invariants + oracles (executable)
+9. `../definition/system.md` → architecture
+10. `../definition/guardrails.md` → security/perf/a11y/i18n
+11. `../definition/features/*.md` → per-flow specs (ephemeral)
+
+## Conventions
+
+- `human/discovery/**` — PM-owned, agent READ-ONLY after Lock
+- `human/definition/**` — Tech-owned, agent READ-ONLY after Lock
+- `agent/**` — Agent-owned, auto-generated, human READ-ONLY
+- `joint/**` — Both append (decisions, test reports)
+
+## Status Legend
+
+- `DRAFT` — agent drafted, human not yet approved
+- `LOCKED` — human approved, agent must use `agent/proposals/` to suggest changes
+- `AUTO` — regenerated on `leancraft sync`
+
+## Agent Usage
+
+Agent MUST read `config.json` → this file → `00-overview.md` → target doc, in order. Never skip.
+Run `npm run leancraft:validate` before asking to Lock.
+
+## Validation
+
+- [ ] All 4 sections present
+- [ ] No TODO/TBD

package/.leancraft/human/discovery/00-overview.md

@@ -0,0 +1,31 @@
+# 00 — Overview — Elevator Pitch & Stack
+
+> Status: DRAFT — Fill then validate
+
+## Elevator Pitch
+
+[TODO: 1 paragraph — what it is, for whom, why now]
+
+## Brand Shape
+
+- Parent brand:
+- Sub-brands:
+- Promise:
+
+## Tech Stack (pinned versions)
+
+- Frontend:
+- Backend:
+- DB:
+- Infra:
+
+## Cost Ceiling
+
+- Target infra cost: $__/mo (must have $)
+- Per-user ceiling:
+- Tracker: `agent/status.md`
+
+## Validation
+
+- [ ] Cost ceiling has $ with currency
+- [ ] Stack has pinned versions

package/.leancraft/human/discovery/01-vision.md

@@ -0,0 +1,29 @@
+# 01 — Vision — North Star & 3-Year
+
+> Status: DRAFT
+
+## North Star
+
+[TODO: 1 sentence — world with product vs without]
+
+## 10x vs Parity Matrix
+
+| Capability | Parity (must match) | 10x (our wedge) |
+|---|---|---|
+|  |  |  |
+|  |  |  |
+|  |  |  |
+
+## 3-Year Vision
+
+- Year 1:
+- Year 2:
+- Year 3:
+
+## Non-Goals (explicit)
+
+- Not building:
+
+## Validation
+
+- [ ] ≥3 wedges in 10x column