Skip to content

project(public-launch): Public Launch — the project-spec (never merged) - #2359

Merged
jhoffner merged 3 commits into
mainfrom
project/public-launch
Sep 29, 2026
Merged

jhoffner merged 3 commits into
mainfrom
project/public-launch

Conversation

@jhoffner

@jhoffner jhoffner commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Public Launch takes FSD from "the framework runs" to "a stranger can install it, build with it, and not be hurt by it". This PR is the project's standing spec. It is never merged and stays open for the life of the project. As of 2026-09-29 · head bd55748a.

Winning when A stranger goes from one command to a working app streaming from a real model, in a new or existing project, without cloning our repo. Every public package installs and imports from npm, and there is no known cross-user leak or silent data loss
The read Five checks of "launched" from a clean machine: packages import · one command to a streaming app · a first flow from docs alone · no open hard gate · the showcase paths run on the public deploy (working, not polished: PD-2). None shown today
Now 0 done · 1 in flight · 1 not started · 2 not filed
Kill line If the hard-gates list grows faster than it closes, shrink the cut (a 0.x release to a small cohort). Don't relax the gates

The territory: four launch tracks inside the project, the framework's own projects as substrate below a fence with simplification the one the launch waits for, and polish, parked bets and post-launch growth outside

The fence asks whether a stranger would hit it, or be harmed by it, the day the doors open. Anything else ships on its own project's timeline, except framework simplification, which the launch waits for.

The arc: the first hour in flight since Aug 20, hard gates with its objective in review since Sep 29 and no bar yet, two unfiled lanes

The first hour is the only bar so far. Hard gates' objective is in review, and its bar starts when that objective is approved.

The epics (live table): FIX-1161 first hour, in flight · FIX-1635 hard gates, not started, objective in review on #2360 · docs, brand and demo bar, not filed · the launch cut, not filed.

Need your sign-off

Launch as 1.0, or as 0.x? A 1.0 launch promises installers we won't break them without a major version. It also turns every public API shape into a launch gate, which widens hard gates from a defect list into an API review. I recommend 0.x, stated plainly in the announcement, with 1.0 as its own milestone after the first cohort. I'd change my mind if a design partner or launch channel needs a stability promise on day one. Being wrong is one-way: 0.x to 1.0 later is cheap, breaking a 1.0 API costs trust. Worth answering before FIX-1635's objective gate, which is now open on #2360. Full ask, with its trade-off figure: DECISIONS.md → Open. It comes down to FIX-1635's scope: 1.0 turns a defect list into a full API review.

Reviewers · look here

  • Is the outcome the right finish line, and are the two placeholder epics (docs, brand and demo bar; the launch cut) the right way to hold the launch items that have no epic yet?
  • PD-2, what counts as a hard gate, binds every epic that calls something launch-blocking. The docs, brand and demo bar gates the cut on launch checks 3 and 5 only.
  • The project's earlier Linear description is kept word for word in absorbed/linear-content.md. Its definition of launched, its scope, what it excluded, and its dependencies were folded in. Two open questions were left for the epics that own them: the scaffold's package name (FIX-1162) and the number of starters (FIX-548).

Spec · Decisions · Rules · Plan · Linear project

How to review this

This is a project-spec: the standing outcome, the cross-epic decisions, and the live state of
one Linear project, in four documents. It is not an implementation plan, not any one epic's
objective, and not a design.

In scope to challenge:

  • The outcome — is this what the project should be driving at, and would we know if we got there?
  • Whether the project overbuilds. Each epic can earn its place while the whole is too much.
    That question can only be asked here.
  • A decision in DECISIONS.md that binds several epics, or a rule in BUSINESS-RULES.md with no
    owner or two.
  • A missing epic the outcome implies, or one listed that does not serve it.

Out of scope — owned by the epic specs below it:

  • Any single epic's objective, issue division, or internals. Those are its epic PR.
  • The figures at the pixel level, and the status in the epics table, which is refreshed as
    the project moves and is never a review finding.

Feedback in the second list is routed to the epic it concerns, not folded in here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G

…fore the first build

The project-spec mirror will replace the Linear project's content field.
This is the field exactly as read on 2026-09-29, so every fold-or-drop
call made in the build is reversible from git.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
The outcome, the territory and the epics table (FIX-1161 in flight,
FIX-1635 filed, two placeholders), three cross-epic decisions and one
open ask (1.0 or 0.x), one rule with an owner, and the arc.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
@vercel

vercel Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Sep 29, 2026 12:22pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Sep 29, 2026 12:22pm UTC
flow-state-dev-ui Ignored Ignored Preview Sep 29, 2026 12:22pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 29, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-29T12:15:57.673921Z f36fe82 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

Second look: PR #2359 (project-spec, docs only)

Scope of the review. Seven files under spec/_projects/public-launch/. There is no code, so there is no refactor opportunity for improve-codebase-architecture, and I'm not proposing one. What follows is the second-look question: does the approach earn its scope, and what's the leaner version?

Findings, ranked

  1. The absorbed launch criteria don't all land anywhere. The original Linear content had six "definition of launched" items. SPEC.md "The read" has five checks. The dropped ones are the pre-launch testing harnesses (item 6) and brand/positioning coherence (item 5). Brand is covered indirectly through FIX-551, but the testing item is orphaned. FIX-488, FIX-107 (docs hybrid search, named in the original's docs bar) and FIX-25 (showcase candidates) don't appear in PLAN.md's "Issues in the project with no epic" list, which does list FIX-489 and FIX-214.

    • The PR body says the original content was "folded in", so the reader will assume nothing was lost.
    • Suggestion: either add those issues to the placeholder assignments in PLAN.md, or say in one line in PLAN.md or DECISIONS.md that "pre-launch testing" was deliberately dropped as a launch check. That would be a scope call, so it's better made by a person than by omission.
  2. Check 5 ("the demo works on the public deploy") has no owner. The only candidate is the unfiled "docs, brand and demo bar" placeholder. BUSINESS-RULES.md has a single rule, and it is about packages loading. Two of the five launch checks (docs-only first flow, demo works) are therefore owned by an epic that doesn't exist yet. That's fine for now, but the spec should say when the placeholder gets filed. Today PLAN.md only says the launch cut is filed "once hard gates and the first hour are both close to done". Nothing says when the docs/brand/demo epic gets filed.

  3. The kill line doesn't cover the risk the data shows. FIX-1161 has been in flight for six weeks with 6 children and none done. The arc figure shows that plainly. The kill line only watches the hard-gates list growing. If the leaner reading is "the launch is gated by its slowest epic", the first hour is the critical path, and the spec has no trigger for it stalling.

    • Suggestion: add a second kill-line clause, or a note in PLAN.md, on what happens if the first hour is still at zero children done at some checkpoint.
  4. PR-1's check doesn't exist yet. The rule says "FIX-1431 and FIX-1334's checks, not written yet". A rule whose only verifier is unwritten is a promise, not a rule. It's honest that it says so. Consider marking PR-1 as unverified in the table (for example a "Checked where" of "none yet"), so a later refresh doesn't read it as enforced.

  5. The same status is stated in five places. The epic table, the mermaid graph, territory.svg, arc.svg, and the PLAN.md table all restate the four epics and their state. Every refresh has to touch all five, and the status tally ("0 done · 1 in flight · 1 not started · 2 not filed") also appears in the PR body. The PR says status is derived from Linear so a missed refresh costs nothing, but with this much duplication a partial refresh will leave the figures disagreeing with the table.

    • Leaner version: SPEC.md's table is the only status source. PLAN.md keeps only order and hand-offs (its Consumes/Releases columns) and drops state. The arc figure carries the only dated state. Not blocking.
  6. Formatting nit, PLAN.md. In the "launch cut" bullet under "What is deliberately not next", the continuation line "needs either answer yet." isn't indented, so it renders as a stray paragraph.

What I checked and would leave alone

  • The two placeholder epics (FIX-XXX) are a reasonable way to hold unfiled launch items. The alternative, filing epics that have no scope yet, is worse. The dashed lanes make their status clear.
  • PD-1 to PD-3 each bind more than one epic, so they earn a place in DECISIONS.md. The 1.0 vs 0.x recommendation is well-formed and correctly separated from the locked decisions.
  • Keeping the verbatim snapshot in absorbed/ is the right call for provenance.

No changes are needed to merge-readiness, since this PR is never merged. Items 1 to 3 are the ones I'd fold before the FIX-1635 objective gate.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Coherence check (FSD Architect) — not owner approval / not the gate. Shared jhoffner login can look like product-owner sign-off; this is approach/coherence only.

Verdict: No two-direction fork. This is the sole open project(...) never-merge for Public Launch. It matches the Jake+Architect locks already on FIX-1635 / #2357:

  • PD-1 — hard gates and first hour (FIX-1161) stay separate parallel tracks; rejected nest under FIX-1161 or Done FIX-1592.
  • PD-2 — hard gate = stranger harm/block (trust, silent loss, unloadable publish), not polish / parked bets / Ops / Tier B unless Jake expands.
  • PD-3 — children keep their own Linear project homes; launch consumes what has shipped by the cut.
  • PR-1 — published-package loadability owned by FIX-1635; first hour inherits for the scaffold path.

Absorbed Linear content → fence + PD-2 is intentional narrowing, not a silent second launch definition. Closed FIX-1161 epic #1301 correctly noted as surface-only (epic still in flight). Placeholder epics (docs/brand/demo bar; launch cut) are holds, not competing streams. No open competing public-launch / hard-gates project- or epic-spec.

Open ask already on the PR (1.0 vs 0.x): product call; when Jake settles it, record via Decision Manager (D-n), then fold the answer back here before FIX-1635’s objective gate. Architect does not own that issue.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify / architecture read

This PR is not an over-built code change — it is the first spec/_projects/* stand-up, and the shape matches project-spec-template.md, project-agent.md, and spec-figures.md (four docs, territory + arc SVGs, mermaid epic graph, absorbed/linear-content.md). Compared to the absorbed Linear checklist (six launch bullets including kitchen-sink polish and tier 2/3 harness), splitting FIX-1161 vs FIX-1635 (PD-1) and narrowing “launch-blocking” to harm/defect (PD-2) is the simpler product story, not extra complexity. I would not recommend collapsing back into one epic or one mega-checklist.

Where complexity still shows up (doc hygiene, not wrong approach)

  1. The read vs PD-2 — Check (5) (“demo works on the public deploy”) still sounds like the old Linear “kitchen-sink demo-quality” bar, while PD-2 explicitly excludes polish (FIX-1631–1633, etc.) from gates. Worth one crisp sentence on whether (5) means functional showcase paths (docs/demo epic) vs visual polish (not a veto). That removes ambiguity without reopening scope.
  2. Dropped checks — Tier 2/3 testing (old #6) and hybrid search (FIX-107) disappear from the five-check read; only traces in PLAN.md / absorbed. A single decided once line (“FIX-488/489/107 are not one of the five checks unless Jake adds them”) would be cheaper than re-deriving from absorbed content.
  3. Duplication — Status counts (0 done · 1 in flight…) appear in the outcome table and again under the epics table; the fence question appears in SPEC.md, territory SVG, PD-2, and PLAN.md. Template wants the epics table to own status once; PD-2 can own the gate definition with (PD-2) links elsewhere.
  4. Figures — Hand-authored arc/territory SVGs with duplicated :root blocks are template-intended (spec-figures.md: position is the content). Maintenance cost is real (dates, FIX-XXX, six surfaces) but the alternative (mermaid for the arc) would violate the doc. Optional nit: drop unused --prose tokens in both SVGs when you next touch them.
  5. Open 0.x vs 1.0 — Full six-part ask in DECISIONS.md → Open matches project-agent (“record it there”). project-spec-template.md also wants live asks visible in the PR body under Reviewers · look here; if the body does not mirror this fork yet, add a short pointer there so epic-lifecycle callers do not have to scrape DECISIONS.md.
  6. PLAN.md issue laundry — The long unassigned-issue paragraph will stale quickly; linking the Linear project filter + naming only launch-cut placeholders might be enough.

Approaches I considered and would not take

  • Single epic for launch — Rejected by PD-1; would mix stranger path and defect closure and make “done” untestable.
  • Keep all six Linear bullets as launch gates — Re-expands scope; PD-2 is the simplification.
  • Shared external CSS for SVGs — Breaks self-contained figure rule in spec-figures.md; duplicate inline CSS is the repo norm (see epic figures like FIX-1553).
  • Skip arc until hard-gates objective approval — Valid bootstrap shortcut; keeping an mostly-empty arc is still template-correct.

Third-party / reuse

No custom tooling needed; the “package” here is the documented project-spec stack. absorbed/ is the prescribed verbatim capture, not extra ceremony.

Verdict: Direction and structure look right for a never-merged project-spec. Approving; inline comments are the highest-leverage simplifications if you want a follow-up edit on this branch.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread spec/_projects/public-launch/SPEC.md Resolved
Comment thread spec/_projects/public-launch/SPEC.md Resolved
Comment thread spec/_projects/public-launch/PLAN.md Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob — too small / already tight. No POC.

I read spec/_projects/public-launch/SPEC.md, DECISIONS.md, BUSINESS-RULES.md, PLAN.md, absorbed/linear-content.md, figures/territory.svg, and figures/arc.svg, against the project-spec template.

A rewrite would not shrink the contract. The template already requires the four documents, the territory figure, the arc figure, and the mermaid graph. Those are containment, time, and handoff, not five copies of one status board. Prose is on the budgets (SPEC 760 vs ~700, decisions 767 vs ~900, plan 480 vs ~700, rules 172 vs ~600). The opening paragraph of SPEC.md repeats the Winning when row; deleting it leaves the required table saying the same thing. The theme blocks repeated in the two SVGs cannot be shared, because each figure has to stay self-contained. absorbed/linear-content.md is the verbatim Linear snapshot, so folding it would drop the reversible read.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f36fe82911

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/_projects/public-launch/SPEC.md Resolved
Comment thread spec/_projects/public-launch/SPEC.md Resolved
… bot review

Status: hard gates' objective is in review (PR #2360, closure FIX-1636
filed); the epics table carries epic state only, counts live once in Now.

Folded from #2359 review: check 5 means the showcase paths run, not
polish; the docs, brand and demo bar gates the cut on checks 3 and 5
only; framework simplification is the one exception to whatever-landed;
a decided-once line for tier 2/3 testing and FIX-107; PR-1's checked
where points at FIX-1636's closure run; the territory figure holds no
live status; the open 1.0-vs-0.x fork gets its trade-off figure.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HNTQkGXCUryuVD2TEBLi6G
@jhoffner
jhoffner merged commit ba29a29 into main Sep 29, 2026
12 checks passed
jhoffner pushed a commit that referenced this pull request Sep 29, 2026
Process guards fails on main since #2359 put spec/_projects on it; #2392
removes it. Same deletion here, a no-op once #2392 merges.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014LohgYyHsXCYQd6kABH11N

jhoffner commented Oct 1, 2026

Copy link
Copy Markdown
Collaborator Author

This PR was merged by mistake on 2026-09-29, and main has since dropped spec/_projects/ again (#2392). The Public Launch project-spec now stands on #2585, a draft from the same project/public-launch branch so it can't be merged. The branch carries FIX-1635's wrap as of 2026-10-01.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants