b2c-app-builder 0.221.39

package/catalog/generated/firstparty/knowledge/product/social-network.md

@@ -0,0 +1,117 @@
+# Social / Community Platform Build Lane
+
+Use this reference when the founder's request is to build a **social or community platform** — "build a social network", "X/Twitter clone", "Instagram clone", "TikTok clone", "a community app for <niche>", "a forum/feed app", "people post and follow each other". It is the first **app-archetype prompt pack**: a recognizable B2C product shape with a known set of core systems and a battle-tested build sequence, shipped as reusable boilerplate prompts under [`../surfaces/starters/social-network/`](../../surfaces/starters/social-network/README.md).
+
+This lane does **not** replace the launch workflow in `SKILL.md`. It is a layer on top of it: it gives the engineering/build stages a proven sequence and ready prompts for one product shape, and it routes each piece back into the existing lanes (research, 11-star, design, security, revenue, growth, analytics). Do not use it to skip evidence, design, security, or provider-proof gates.
+
+## When To Use
+
+Load this reference when:
+
+- The founder describes a product whose core is **posts + a social graph + a feed + engagement + notifications** (the five core systems below), regardless of the content format.
+- The request names a comparable platform (X, Instagram, TikTok, Reddit, Discord, BeReal, Substack-as-network) or a niche community version of one.
+- You are at the spec/engineering/handoff stage of such a product and want the boilerplate prompt sequence instead of improvising the schema and feed from scratch.
+
+Do **not** force this lane onto a product that merely has a comment section or a single social feature; it is for products whose center of gravity is the social loop.
+
+## Step 1 — Detect The Archetype And Confirm The Variant (AskUserQuestion)
+
+Before writing schema or specs, confirm the product shape with the founder using **AskUserQuestion** (or a plain founder choice if AskUserQuestion is unavailable). This is a bounded product-shape decision that changes the schema, the feed, the design, and the store path — it is worth one upfront question, and it is not a founder-only gate that blocks other work.
+
+Ask, in one batched call:
+
+1. **Content format** — what is a "post" at its core?
+   - **Text-first** (X/Twitter model): short text, optional images. Feed is a timeline list.
+   - **Image-first** (Instagram model): at least one image required, optional caption. Feed is a grid; adds Stories + Explore.
+   - **Video-first** (TikTok model): short vertical video. Feed is full-screen, swipe-driven, algorithmic.
+2. **Primary surface** — where does the accepted product run?
+   - **Web / PWA** (the prompt pack's default stack: Next.js App Router + Supabase + Vercel).
+   - **Native mobile** (iOS/Android): the same five systems and Supabase backend hold, but the client prompts must be re-expressed for the native stack and the Apple/Play store lanes in `SKILL.md` apply in full.
+3. **Which optional systems are in the accepted product?** (multi-select) — direct messages, monetization (subscriptions + creator support), invite-only onboarding, search/discovery. These map to the optional prompts in the pack.
+4. **Niche** — who is this community for? (Free text. Feeds Step 2 positioning. A focused niche is the whole strategy: a smaller, highly engaged community beats a general-purpose clone.)
+
+Record the answers in `state/business-state.json` (under the product lane, e.g. `lanes.product.archetype: social-network`, `content_format`, `primary_surface`, `optional_systems`) so later sessions do not re-litigate the shape.
+
+Honesty note on the stack: the bundled prompts target **web (Next.js + Supabase + Vercel)** because that is the fastest path to a working multi-user social product. If the founder picks native mobile, say so plainly — the schema, RLS, real-time, and storage prompts carry over unchanged, but the auth/feed/profile/DM client prompts are web prompts and must be adapted, and the full iOS signing/ASC/store lanes become required rather than optional.
+
+## Runnable Starter
+
+The pack ships a runnable scaffold at [`../surfaces/starters/social-network/starter/`](../../surfaces/starters/social-network/starter/README.md): Next.js App Router + Supabase pre-wired with magic-link auth, schema migrations with **tested** RLS (pgTAP, per `backend-data-contract.md`), Stripe and RevenueCat stubs, a PostHog event catalog matching the analytics lane's snake_case conventions, a names-only `.env.example`, and a CI workflow. Copy it into the business repo as the floor and customize it with the prompts below — its README maps each prompt to the scaffold area it customizes. Do not improvise the same wiring from scratch; `check:archetype-starter` enforces the starter contract. If the founder selects Firebase or a custom backend, adapt through the data-contract lane instead of running the Supabase pieces verbatim.
+
+## The Five Core Systems
+
+Every social platform — text, image, or video — is built on the same five systems. If any one is missing or broken, the product does not work. The build sequence exists to complete them in dependency order.
+
+1. **User Identity** — registration, authentication, sessions, profiles, verification. First built, last revisited. → prompt `02-auth-system`, profile half of `04-profiles-and-follow`.
+2. **Content Creation & Storage** — posts, media in object storage, validation, association to the creator. Only the media type changes between variants. → prompt `01-database-schema`, `03-feed-and-posts`, plus the variant deltas.
+3. **Social Graph** — who follows whom (asymmetric for the X model). The most performance-sensitive part; it decides what reaches each feed. → follow half of `04-profiles-and-follow`.
+4. **Feed** — what each user sees and in what order. Choose chronological ordering when it serves the accepted user promise (understandable, debuggable, trusted). A required ranked or hybrid feed must be implemented and verified, not deferred as a shortcut. The video-first variant is the exception — it needs a recommendation mix from day one. → `03-feed-and-posts`, video-first variant.
+5. **Engagement & Reactions** — likes, reposts, replies/comments, and the notifications they generate. Notifications must be async and not block the main request cycle. → engagement half of `03-feed-and-posts`, notification half of `04-profiles-and-follow`.
+
+## The Build Sequence
+
+Build **one system at a time, test it, then move on**. A solid identity + feed beats ten half-built features. Run the prompts in this order; each lives in [`../surfaces/starters/social-network/prompts/`](../../surfaces/starters/social-network/README.md):
+
+| #   | Prompt                                           | Core system                      | Threads into                                                                    |
+| --- | ------------------------------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
+| 00  | `00-niche-strategy` (Claude.ai, not Claude Code) | positioning                      | `strategy/RESEARCH.md`, naming, `VIRAL_GROWTH.md`, `growth/LAUNCH_NARRATIVE.md` |
+| 01  | `01-database-schema`                             | content + graph + engagement     | `engineering/TECH_SPEC.md`, engineering lane, security (RLS)                    |
+| 02  | `02-auth-system`                                 | identity                         | engineering, `trust/SECURITY.md`, `SECRETS.md` (OAuth keys)                     |
+| 03  | `03-feed-and-posts`                              | content + feed + engagement      | `11_STAR_EXPERIENCE.md` core loop, `analytics/ANALYTICS.md` events              |
+| 04  | `04-profiles-and-follow`                         | identity + graph + notifications | engineering, real-time, `analytics/ANALYTICS.md`                                |
+| 05  | `05-search-and-discovery` (optional)             | discovery                        | engineering, growth                                                             |
+| 06  | `06-direct-messages` (optional)                  | engagement                       | engineering, real-time, abuse controls                                          |
+| 07  | `07-stripe-monetization` (optional)              | revenue                          | `revenue-monetization.md`, `revenue/REVENUE_OPS.md`                             |
+| 08  | `08-invite-system` (optional)                    | growth                           | `viral-growth-loops.md`, `VIRAL_GROWTH.md`                                      |
+
+Variants (apply after the text-first base, or fold into prompt 01/03 if chosen upfront): [`variants/image-first-instagram`](../../surfaces/starters/social-network/prompts/variants/image-first-instagram.md) and [`variants/video-first-tiktok`](../../surfaces/starters/social-network/prompts/variants/video-first-tiktok.md).
+
+Step 0 (niche strategy) is strategic work for the **web interface / Claude.ai**, not Claude Code — it is about people, not systems. The rest are Claude Code build prompts.
+
+## How This Lane Threads Into The Launch Workflow
+
+The prompt pack is the engineering spine, not the whole launch. Keep these connections live:
+
+- **Database schema first.** Prompt 01 produces the schema every other system builds on; getting it wrong means expensive rewrites. Reconcile it with `engineering/TECH_SPEC.md` (data model, API contracts, RLS policies) before building clients.
+- **Row Level Security is the security lane, not a checkbox.** The schema prompt emits Supabase RLS so users can only edit their own data. Treat RLS policies as part of `security-release-hardening.md`: every table that holds user data needs a policy and a test, and entitlement/visibility rules (private accounts, blocks) belong in the threat model.
+- **The feed is the 11-star core loop.** Prompt 03 is where the defining product moment lives. Run [`eleven-star-experience.md`](../experience/eleven-star-experience.md) over it, and name the optimistic-UI like/repost reveal and the real-time arrival of new posts as engineered moments with PostHog events and reduced-motion fallbacks (`consumer-product-design-agency.md`, `emotional-design-system.md`).
+- **Monetization reconciles with the revenue lane.** Prompt 07 uses **Stripe** (Checkout + Customer Portal + Connect for creator payouts) because the default surface is web. If the founder ships native iOS, digital subscriptions generally must go through StoreKit/IAP (route via `revenue-monetization.md` and RevenueCat); Stripe Connect creator payouts and physical/real-world value can stay on Stripe. Do not ship the web Stripe paywall inside an iOS binary without resolving App Store policy first.
+- **Invites are a growth loop, not just a gate.** Prompt 08 feeds `viral-growth-loops.md`: invite acceptance rate, inviter attribution, and the invitation tree are the loop's analytics. Pre-loading value before opening the doors (build-in-public → invite-only beta → referral codes) is the standard cold-start sequence.
+- **Positioning feeds research and launch.** Prompt 00's outputs (what the community hates about incumbents, the one tell-a-friend feature, name directions, first-100-users plan) flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.
+- **Analytics before surfaces lock.** Every engagement and notification path named in prompts 03/04/06 needs an event in `analytics/ANALYTICS.md` before build (`analytics-attribution.md`).
+- **Don't optimize for scale before users.** Build the monolith, ship it, get users, then optimize the queries that actually become bottlenecks. A feed query that is inefficient at 100 users is fine until ~10,000.
+
+## Infrastructure Defaults (record decisions, do not hardcode)
+
+These are the pack's default choices; confirm and record them in `strategy/TOOL_DECISIONS.md` / `SECRETS.md` rather than assuming:
+
+- **Backend:** Supabase (Postgres + Auth + Realtime + Storage). Object storage for all media — never serve media from the app server. At significant media volume, migrate to Cloudflare R2 (zero egress).
+- **Hosting:** Vercel (preview URL per PR, global CDN) for the web surface.
+- **Video transcoding (video-first only):** Mux or Cloudflare Stream for adaptive bitrate.
+- **Email:** route through the existing `resend-email-ops.md` lane (verification, follower/notification digests).
+- **Moderation from day one:** rate limiting on post creation, a basic word filter, image moderation (Google Vision / AWS Rekognition), and text classification (Claude API) before opening publicly. This is a launch gate for any public social product, not optional future polish.
+
+## Extending This Layer With New Archetypes
+
+This is the first archetype pack. To add another (e.g. marketplace, dating, journaling, habit-tracker):
+
+1. Add `starters/<archetype>/README.md` + `prompts/` with the same shape (numbered, dependency-ordered, copy-paste-ready prompts with skill-integration notes).
+2. Add a peer reference (or a section here) describing its core systems, the AskUserQuestion shape, and how each prompt threads into the existing lanes.
+3. Wire it into `SKILL.md` (archetype-detection step + a When-To-Load rule) and add an agent-behavior eval that locks in "detect archetype → confirm via AskUserQuestion → load the pack → sequence the prompts".
+4. Keep the prompts faithful to their source but improve them to match this skill's contracts (RLS, analytics events, reduced-motion, provider proof).
+
+## Acceptance Checklist
+
+Before calling a social-platform build ready:
+
+- [ ] Archetype + content format + primary surface + optional systems confirmed via AskUserQuestion and recorded in `state/business-state.json`.
+- [ ] Schema (prompt 01) reconciled with `engineering/TECH_SPEC.md`; every user-data table has a tested RLS policy referenced from `trust/SECURITY.md`.
+- [ ] The five core systems are each complete and tested before dependent features start.
+- [ ] The feed core loop is run through `11_STAR_EXPERIENCE.md` with named engineered moments and PostHog events in `analytics/ANALYTICS.md`.
+- [ ] Monetization (if in scope) is reconciled with `revenue-monetization.md` and the correct billing path for the chosen surface (Stripe for web; IAP/StoreKit for native digital subscriptions).
+- [ ] Invite/referral mechanics (if in scope) are tied to `viral-growth-loops.md` with acceptance-rate and attribution analytics and self-referral/abuse controls.
+- [ ] Moderation baseline (rate limits, word filter, image + text classification) is specified before any public launch.
+- [ ] Positioning outputs from prompt 00 flow into `strategy/RESEARCH.md`, naming, and `growth/LAUNCH_NARRATIVE.md`.
+</content>
+
+</invoke>

package/catalog/generated/firstparty/knowledge/research/distribution-first-niche.md

@@ -0,0 +1,70 @@
+# Distribution-First Niche
+
+Use this before Phase 2 design or build work.
+Name a paying audience and one reachable channel first.
+Code does not create distribution.
+
+Purchases validate the niche.
+Compliments, likes, and waitlist-only interest do not.
+
+## Contents
+
+- 1. Pre-Build Gate
+- 2. Press Pack
+- 3. Influencer Pack
+- 4. Outputs
+- 5. Common Failure Modes
+
+## 1. Pre-Build Gate
+
+Record a Distribution-First Niche table in `strategy/RESEARCH.md`.
+
+The table must name:
+
+- who already pays for this job
+- one named channel the founder can reach
+- the paid event that counts as validation
+
+A named channel is a community, creator list, search cluster, or partner list.
+"Social media", "online", "ads", and "organic" are not named channels.
+
+`check:research` reads this table when the research lane is done.
+Distribution Proof still records reach evidence.
+This table records that the audience already pays and that purchases, not compliments, count.
+
+## 2. Press Pack
+
+Keep press work as a short checklist.
+Do not build a second outreach system.
+
+- shortlist two or three outlets that already cover this job
+- write one email that leads with the transformation demo
+- offer TestFlight as the launch artifact, not a feature tour
+
+Load `launch-narrative-cadence.md` for public posting rules.
+The founder approves every outbound email.
+
+## 3. Influencer Pack
+
+Load `influencer-sponsorship-engine.md` for native-fit filters, view-guarantee deals, and disclosure.
+Load `ugc-creator-engine.md` for hired posts on accounts the program controls.
+
+Do not start creator spend from this file.
+This file only requires that purchases, not compliments, validate a fit.
+
+Native-fit means the creator already speaks to people who pay for this job.
+A view guarantee is a deal term in the influencer engine.
+It is not a reason to skip the paying-audience row here.
+
+## 4. Outputs
+
+- `strategy/RESEARCH.md` Distribution-First Niche table
+- press shortlist and one-email draft, founder-gated
+- influencer prospects only after the niche table passes
+
+## 5. Common Failure Modes
+
+- Build starts with no paying audience
+- Channel recorded as "social media"
+- Waitlist compliments used as validation
+- Press or influencer spend before the niche table exists

package/catalog/generated/firstparty/knowledge/research/distribution-offer-signal.md

@@ -0,0 +1,190 @@
+# Distribution, Offer, And Signal Validation
+
+Use this reference before the founder records a Go, Pivot, or Kill decision.
+It adds distribution and offer evidence to the pre-build decision.
+
+## 1. Required Outcome
+
+Research must answer five questions before design or build work starts:
+
+1. Which people have the problem?
+2. Where do these people seek a solution?
+3. Which native message or format can reach them?
+4. Does a measurable offer response exist?
+5. How will the business keep an owned relationship after discovery?
+
+Category revenue proves that money exists in a market.
+It does not prove that this business can reach the market.
+
+### Strict Evidence Markdown
+
+Validator-backed evidence sections use a narrow Markdown dialect. Each section has one exact rendered H2 and one simple pipe table. Validators resolve required columns by name. Approved column-zero backtick and tilde fences may hold hidden examples. Outside those fences, every nonblank line indented four or more columns invalidates the evidence document. HTML comment opener tokens, raw HTML block syntax, non-column-zero fences, and container-relative raw HTML also invalidate it. Write checkable records as top-level Markdown.
+
+## 2. Distribution Proof
+
+Record distribution proof in `strategy/RESEARCH.md`.
+Use evidence from a current source ledger row.
+Give that row a stable source or trace ID in its URL/source-ID or Artifact/trace cell.
+The Distribution Proof evidence cell must resolve to that ledger ID or to a `current` or `dated` Signal ID.
+Do not use an unverified, rejected, or superseded signal as distribution proof.
+
+The proof must identify:
+
+- one audience segment
+- one exact discovery location
+- one native content or outreach format
+- one route to an owned relationship
+- one measured signal from that route
+
+An exact location is a named search result, community, creator audience, keyword cluster, newsletter, ad placement, or partner channel.
+"Social media" is not an exact location.
+
+An owned relationship is an email subscriber, account, push permission, or direct community membership.
+Do not require email when another durable route fits the product better.
+
+## 3. Signal Corpus
+
+Write `strategy/SIGNAL_CORPUS.md` before every pre-build verdict when reusable source material exists. Source material can include posts, transcripts, reviews, interviews, support records, and prior launch material. When no reusable source exists, keep the artifact. Record a project-specific `Status: not applicable —` reason. The reason must explain why no reusable source material exists. Do not invent evidence. Do not use `none`, `n/a`, `not applicable`, `unknown`, `no reason`, literal `authored reason` text, or an angle-bracket instruction.
+
+Record every source in Corpus Inputs before you cite it.
+Give each input a stable `INPUT-` ID, a real date range, an owner or creator, a collection route, a permission or public basis, and collection limits.
+Every Source ID in Signal Records must resolve to a declared input.
+
+Keep one signal record for one claim.
+Each record must include:
+
+- a stable signal ID
+- a signal type
+- the claim or exact phrase
+- one or more source IDs
+- an observation date
+- an applicability statement
+- a confidence value
+- a lifecycle status
+- a trace pointer
+
+Use these lifecycle values:
+
+- `current`: the evidence supports current use
+- `dated`: the record can still inform work, but time can change it
+- `superseded`: a later record replaces it
+- `rejected`: the evidence does not support use
+- `unverified`: the record needs more evidence
+
+A superseded record must point to its replacement.
+Do not delete a material contradiction.
+Record the contradiction and the selected current position.
+Unverified, rejected, and superseded records can remain in the corpus.
+Only `current` and `dated` records can support Distribution Proof or Derived Outputs.
+
+Markdown is the authoritative record.
+Indexes, search data, charts, and embeddings are rebuildable outputs.
+
+## 4. Traffic-Backed Offer Test
+
+Write `strategy/OFFER_TEST.md` before the founder records the verdict.
+Use the smallest truthful offer surface that can measure response.
+Replace every starter field with one project-specific value.
+A menu of possible audiences, locations, formats, relationship routes, responses, or stop rules is guidance, not a completed test contract.
+The Owned relationship field must name one durable route.
+An absent route does not complete the contract.
+
+The test can use:
+
+- a plain landing page
+- an existing store page
+- a direct-outreach offer
+- a partner or creator placement
+- a community post with a measurable call to action
+
+The test must record exposure and response.
+Exposure can be impressions, qualified visits, or qualified direct contacts.
+Response can be sign-ups, deposits, purchases, booked calls, or another named action.
+
+Do not treat compliments, likes, or general survey interest as an offer response.
+
+Public deployment, account connection, and spend need the applicable founder authority.
+Research can prepare the test without that authority.
+
+If the founder declines or cannot run the test, record a waiver.
+The waiver must include the founder, date, reason, and residual risk.
+Silence is not a waiver.
+
+## 5. Decision Use
+
+Add `Distribution proof` and `Offer test` columns to the Go, Pivot, Or Kill table.
+The founder decides the verdict after these columns contain evidence.
+
+A zero-conversion test does not force an automatic Kill decision.
+It is evidence for the founder to judge.
+The test can expose a bad audience, channel, message, offer, or product promise.
+
+## 6. Owned-Relationship Metrics
+
+When the project continues, track these metrics by discovery channel:
+
+- discovery exposure to owned contact
+- owned contact to activation
+- owned contact to paid conversion
+- revenue per owned contact
+- share of acquisition from the largest external platform
+
+Raw reach is a diagnostic value.
+It is not a business outcome.
+
+## 7. Content Intelligence
+
+Store reusable content observations as structured records.
+Each record should include the source, account baseline, audience fit, hook, structure, emotion, format, sales intent, and downstream result.
+
+Normalize performance against the source account's usual result.
+Do not rank content by raw views alone.
+
+Extract patterns.
+Do not copy another creator's words, identity, assets, or exact composition.
+
+## 8. Manual Proof Before Automation
+
+Run each value-producing process manually before you automate it.
+Record the manual input, output, result, cost, and failure mode.
+
+This rule does not apply to necessary security, compliance, backup, or monitoring controls.
+
+Begin each automation decision with `automate` or `keep manual`. Use `automate` only when that process's row passed and its manual evidence shows that repetition has value.
+
+## 9. Optional Persona-Balanced Test Planning
+
+When a beta test is in scope, a mixed group can help plan complementary perspectives:
+
+- a target novice
+- a target experienced user
+- a user who represents a device or accessibility risk
+- a domain, product, or usability reviewer
+
+Use the worksheet only when it helps the project plan recruitment or interpret feedback.
+It is optional planning guidance, not app-quality completion evidence.
+It does not replace measured quality results or change fresh-context acceptance of the whole app-quality artifact.
+Do not use one tester group as a fixed quota for every product, and do not treat a filled worksheet as proof that the app passed quality review.
+
+## 10. Prohibited Transfers
+
+Do not transfer deceptive or unsafe tactics from source material.
+Prohibited tactics include:
+
+- hidden fees
+- fake scarcity or social proof
+- undisclosed engagement manipulation
+- platform-rule circumvention
+- safety-filter evasion
+- close copying of successful content or ads
+
+Treat strong universal claims as hypotheses.
+Test them against this business's evidence.
+
+## 11. Source Limits
+
+EP's Signal Knowledgebase is a primary example of corpus compression and portable publishing.
+It also contains personal claims, dated tool choices, and aggressive growth tactics.
+
+Use its information architecture and testable business hypotheses.
+Do not treat its business claims as verified facts.

package/catalog/generated/firstparty/knowledge/research/go-pivot-or-kill.md

@@ -0,0 +1,120 @@
+# Go, Pivot, Or Kill: The Pre-Build Research Verdict
+
+The launch machinery will polish and ship whatever idea it is given — it has no opinion on
+whether the idea is worth building. This is the one evidence-gated exit ramp before Phase 2
+spends design, build, and store effort: the agent assembles the evidence, the founder decides
+whether the category and the wedge earn a build. `check:research` enforces the shape of this
+decision in `strategy/RESEARCH.md`; this file is the judgment behind that shape, not a second
+copy of it.
+
+## Contents
+
+- 1. The Category Revenue Reality Bar
+- 2. The Go, Pivot, Or Kill Table Contract
+- 3. The Verdict Is Founder-Only
+- 4. What Kill And Pivot Mean
+- 5. When The Verdict Is Mandatory
+
+## 1. The Category Revenue Reality Bar
+
+Before the spec hardens, ask the question a good idea and a good business both answer
+differently: **is this market big enough to be worth building in at all?** Pull top-competitor
+revenue estimates (AppKittie, sorted by revenue) and judge them against a stated bar.
+
+Default bar: the top 10 apps in the target category gross at least **$5M/year combined**, with
+at least **two independent apps each clearing $1M/year**. A category whose leaders gross too
+little cannot become a real business however well the launch executes — no amount of good
+onboarding, ASO, or paid UA fixes a market that is not there. Adjust the bar with the founder
+for a deliberate niche play, and record why the adjustment is legitimate rather than a way to
+pass a category that would otherwise fail.
+
+`check:research` reads the `## Category Revenue Reality` section's table, not the phrase in
+prose, and requires:
+
+- at least one competitor row with a real dollar estimate in the revenue column AND a dated
+  (`YYYY-MM-DD`), non-placeholder source in the source column — collecting the AppKittie data
+  is not the gate, the sourced number judged against the bar is
+- a "stated bar" line carrying an actual number, not a blank or placeholder
+- an explicit `pass or fail:` judgment line against that bar
+
+A pass verdict over no stated threshold, or a table with rows but no judgment line, is data
+collection wearing a gate's clothes.
+
+## 2. The Go, Pivot, Or Kill Table Contract
+
+The verdict itself lives in a `## Go, Pivot, Or Kill` table with these required named columns.
+The starter uses this canonical order, but projects may reorder the named columns or add
+project-specific columns:
+
+| Date | Category revenue reality | Wedge | Demand signal | Distribution proof | Offer test | Verdict (Go / Pivot / Kill) | Decided by |
+| ---- | ------------------------ | ----- | ------------- | ------------------ | ---------- | --------------------------- | ---------- |
+
+The five evidence columns are named on purpose: **category revenue reality**, **wedge**,
+**demand signal**, **distribution proof**, and **offer test** are the inputs a real verdict is
+judged from. A table renamed to Notes/Opinion/Summary carries cells, not the required inputs,
+and `check:research` rejects it. The validator resolves the required fields by normalized name,
+not by physical position or by a table shaped roughly like a decision.
+
+Row-level requirements once the lane is done:
+
+- **date and verdict must parse.** The date is ISO (`YYYY-MM-DD`); the verdict cell starts with
+  `go`, `pivot`, or `kill`. A row with a mistyped date or an unparseable verdict is reported as
+  malformed, never silently dropped — dropping it would fall back to an older verdict the
+  founder already superseded.
+- **the latest date wins ties.** If two rows share the newest date, the later row in the table
+  is the one that counts.
+- **evidence cells must be substantive.** Each of the five named evidence cells on the latest
+  row must be non-empty and free of placeholder text (`unverified`, `tbd`, `todo`, `to be
+filled`, `pending`, `placeholder`). A verdict decided over "unverified" is a mood, not a
+  decision — fill category revenue, wedge, demand, distribution, and offer evidence before
+  recording it.
+
+## 3. The Verdict Is Founder-Only
+
+`"Decided by"` names the founder — by role (`founder`, `owner`) or by the name recorded in
+`project.owner` — **never an agent or automation identity**. `check:research` explicitly rejects
+`agent`, `codex`, `claude`, `gpt`, `assistant`, `bot`, `automation`, `autopilot`, and `ai` as
+decision-makers in this column. This is the one gate in the whole engine designed to stop the
+agent from clearing itself: an agent recording Go for itself is the exact bypass the checkpoint
+exists to prevent, however confident the evidence looks.
+
+The verdict and its date must also be mirrored into `state/business-state.json`
+(`lanes.research.go_pivot_kill_decision` / `lanes.research.go_pivot_kill_decided_at`), and the
+mirror must match the latest table row exactly — a stale or forward-dated mirror is what
+downstream lanes and the portfolio pipeline would act on instead of the real decision.
+
+## 4. What Kill And Pivot Mean
+
+A Kill or a Pivot at this checkpoint is the process working, not failing — it costs a research
+document instead of a shipped app nobody wanted.
+
+- **Kill** winds the idea down before any design or build spend. The research lane is not
+  done, and stays not done: `check:research` refuses a `done` status while the latest verdict
+  is anything other than `go`.
+- **Pivot** re-enters Phase 1 with the wedge changed — new positioning, a different core loop,
+  or a narrower niche — and the Category Revenue Reality and Go/Pivot/Kill sections get a fresh
+  row once the changed wedge has been evaluated. The old verdict does not carry forward onto a
+  materially different idea.
+- **Go** is the only verdict that lets the research lane close `done`. Record the follow-up
+  verdict once the founder actually decides to build — a lane cannot be `done` on the strength
+  of the evidence alone.
+
+## 5. When The Verdict Is Mandatory
+
+This checkpoint does not wait politely for the research lane to claim `done` before it starts
+enforcing. `check:research` requires a real verdict the moment any of the following is true:
+
+- `lanes.research.status` is `done`, or
+- `project.phase` is `phase_2` or later, or
+- any downstream lane — `experience`, `product`, `design`, `content_assets`, or
+  `engineering` — is already `partial` or `done`.
+
+The `research-backed-spec` workflow uses `check:research-workflow-output`. This strict wrapper
+also requires complete research, signal-corpus, and offer-test outputs when that workflow claims
+its work. It does not change the pre-claim behavior of the public `check:research` command.
+
+That last condition is the one that matters most in practice: design and build effort spent
+before the founder's verdict is exactly the cost this checkpoint exists to prevent, whatever the
+recorded project phase says. Deferring or marking the research lane `not_needed` does not route
+around this — from `phase_2` onward, or the moment downstream work goes active, the verdict is
+mandatory even for a lane the state file claims is deferred.