Commit9ab6971unknown_key

docs: add BUILD_BIBLE.md — single source of truth for every future session

docs: add BUILD_BIBLE.md — single source of truth for every future session

BUILD_BIBLE.md is mandatory reading for every Claude agent. It pins:
- Agent policy (do-not-undo rule, continuous-build rule, quality bars)
- GitHub parity scorecard (shipped vs partial vs missing)
- Numbered build plan (Blocks A–H)
- Locked components (infra / git / auth / AI / routes / views / tests)
- Session workflow

CLAUDE.md now points at the Bible as required pre-read so no future
session undoes shipped work or stops mid-block waiting for clarification.

https://claude.ai/code/session_01U6sj9ezKCpmiwx7cXGZmS6

Claude committed on April 14, 2026Parent: 3ef4c9d

2 files changed+386−09ab697197e843b742cabc25bd7b88d29509fb5e7

2 changed files+386−0

AddedBUILD_BIBLE.md+373−0View fileUnified Split

@@ -0,0 +1,373 @@

1# GLUECRON BUILD BIBLE

3**This file is the single source of truth for the GlueCron build.**

5**Every Claude agent MUST read this file in full before touching code. No exceptions.**

7GlueCron is a GitHub replacement — AI-native code intelligence, green ecosystem enforcement, git hosting, automated CI. It is production infrastructure for multiple downstream platforms. Production cannot stop.

9---

11## 1. AGENT POLICY (READ FIRST, FOLLOW ALWAYS)

13### 1.1 Required reads at session start

141. `BUILD_BIBLE.md` (this file) — complete

152. `CLAUDE.md` — stack + architecture

163. `README.md` — user-facing overview

174. Most recent commit on the current branch (`git log -1 --stat`)

19### 1.2 Do-not-undo rule

20- Anything listed in **§4 LOCKED BLOCKS** is shipped and must not be deleted, renamed, or semantically altered without the owner's explicit written permission in the current session.

21- "Refactor" is not permission. "Clean up" is not permission. "Simplify" is not permission.

22- If a locked file seems wrong, open an issue in the plan and keep going on a new block.

24### 1.3 Continuous-build rule

25- The owner runs many parallel projects. Do not stop work to ask for clarification that can be inferred from this file.

26- Default behaviour when a block is partially complete: **finish it, run tests, commit, push, start the next block**.

27- Only stop for genuinely blocking decisions: destructive operations, architectural reversals, requests outside this plan, or repeated test failures you can't diagnose.

28- Never stop because "the session might run out." Commit what works and keep building.

30### 1.4 Branch + commit rules

31- Development branch: whatever the current session was told (check session opening message). Fall back to `main` if none given.

32- One commit per completed block. Message format: `feat(BLOCK-ID): <summary>`.

33- Push after every commit with `git push -u origin <branch>`.

34- Never force-push. Never `--no-verify`. Never amend published commits.

36### 1.5 Quality bars (non-negotiable)

37- `bun test` must pass before every commit.

38- New features ship with tests in `src/__tests__/`.

39- New routes use `softAuth` or `requireAuth` middleware.

40- New DB tables have a corresponding migration in `drizzle/`.

41- AI features use `isAiAvailable()` guards and degrade gracefully without `ANTHROPIC_API_KEY`.

42- Every user-facing failure mode has a fallback — no 500s reach the UI.

44### 1.6 Green-ecosystem-by-default

45- Every new repo auto-configures: gates on, branch protection on, labels seeded, CODEOWNERS synced, welcome issue posted.

46- Users can opt out per feature but defaults are maximum-green.

47- Nothing broken ever reaches production, the website, or the customer.

49---

51## 2. GITHUB PARITY SCORECARD

53Legend: ✅ shipped · 🟡 partial · ❌ not built

55### 2.1 Repository hosting

56| Feature | Status | Notes |

57|---|---|---|

58| Git Smart HTTP (clone / push / fetch) | ✅ | `src/routes/git.ts`, `src/git/protocol.ts` |

59| SSH keys | ✅ | `ssh_keys` table, `src/routes/settings.tsx` |

60| Public / private visibility | ✅ | `repositories.isPrivate` |

61| Forking | ✅ | `src/routes/fork.ts` |

62| Stars | ✅ | `stars` table, `/:owner/:repo/star` |

63| Topics | ✅ | `repo_topics` table |

64| Archive / disable repo | ❌ | schema has flags; no UI |

65| Repository transfer | ❌ | — |

66| Template repositories | ❌ | — |

67| Repository mirroring | ❌ | — |

69### 2.2 Code browsing

70| Feature | Status | Notes |

71|---|---|---|

72| File tree browser | ✅ | `src/routes/web.tsx` |

73| Syntax highlighting | ✅ | 40+ languages, `src/lib/highlight.ts` |

74| Commit history | ✅ | |

75| Diffs | ✅ | |

76| Blame | ✅ | |

77| Raw file download | ✅ | |

78| Branch switcher | ✅ | |

79| Tag listing | ✅ | new this build |

80| Code search (ILIKE) | ✅ | per-repo + global |

81| Semantic / embedding search | ❌ | pgvector not wired |

82| Symbol / xref navigation | ❌ | — |

84### 2.3 Collaboration

85| Feature | Status | Notes |

86|---|---|---|

87| Issues (CRUD / comments / labels / close) | ✅ | |

88| Milestones | ✅ | `src/routes/insights.tsx` |

89| Pull requests (CRUD / review / merge) | ✅ | |

90| PR inline comments | ✅ | file+line anchored |

91| Draft PRs | 🟡 | schema flag, no UI toggle |

92| Reactions (emoji) | 🟡 | table exists, no UI |

93| Mentions + notifications | ✅ | `src/routes/notifications.tsx` |

94| Code owners | ✅ | `src/lib/codeowners.ts` |

95| Issue templates | ❌ | |

96| PR templates | ❌ | |

97| Saved replies | ❌ | |

98| Discussions / forums | ❌ | |

99| Wikis | ❌ | |

100| Projects / kanban | ❌ | |

101

102### 2.4 Automation + AI

103| Feature | Status | Notes |

104|---|---|---|

105| Webhooks | ✅ | HMAC signed |

106| Gate runs (test / secret / AI review) | ✅ | `gate_runs` table, `src/routes/gates.tsx` |

107| Branch protection | ✅ | `branch_protection` table + UI |

108| Auto-repair engine | ✅ | `src/lib/auto-repair.ts` |

109| Secret scanner | ✅ | 15 patterns, `src/lib/security-scan.ts` |

110| AI security review | ✅ | Sonnet 4, `src/lib/security-scan.ts` |

111| AI commit messages | ✅ | `src/lib/ai-generators.ts` |

112| AI PR summaries | ✅ | |

113| AI changelogs | ✅ | auto on release create |

114| AI code review | ✅ | `src/lib/ai-review.ts` |

115| AI merge conflict resolver | ✅ | `src/lib/merge-resolver.ts` |

116| AI chat (global + repo) | ✅ | `src/routes/ask.tsx` |

117| GitHub Actions equivalent (workflow runner) | ❌ | GateTest integrated, no generic runner |

118| Dependabot equivalent (AI dep bumper) | ❌ | |

119| Code scanning UI | 🟡 | data exists, no dedicated UI page |

120| Copilot code completion | ❌ | |

121

122### 2.5 Platform

123| Feature | Status | Notes |

124|---|---|---|

125| Dashboard | ✅ | `src/routes/dashboard.tsx` |

126| Explore / discover | ✅ | |

127| Global search | ✅ | repos / users / issues / PRs |

128| Insights (graph, contributors, green rate) | ✅ | `src/routes/insights.tsx` |

129| Releases + tags | ✅ | AI changelog |

130| Personal access tokens | ✅ | SHA-256 hashed |

131| OAuth app provider | ❌ | |

132| GitHub Apps equivalent | ❌ | |

133| GraphQL API | ❌ | REST only |

134| Organizations + teams | ❌ | user-owned only |

135| Enterprise SAML / SSO | ❌ | |

136| 2FA / TOTP | ❌ | |

137| Passkeys / WebAuthn | ❌ | |

138| Packages registry (npm / docker / etc) | ❌ | |

139| Pages / static hosting | ❌ | |

140| Gists | ❌ | |

141| Sponsors | ❌ | |

142| Marketplace | ❌ | |

143| Environments / deployment tracking | 🟡 | `deployments` table, no UI |

144| Merge queues | ❌ | |

145| Required checks matrix | 🟡 | branch_protection has single flag, no matrix |

146

147### 2.6 Observability + safety

148| Feature | Status | Notes |

149|---|---|---|

150| Rate limiting | ✅ | `src/middleware/rate-limit.ts` |

151| Request-ID tracing | ✅ | `src/middleware/request-context.ts` |

152| Health / readiness / metrics | ✅ | `/healthz` `/readyz` `/metrics` |

153| Audit log (table) | ✅ | `audit_log` table |

154| Audit log UI | ❌ | data only |

155| Traffic analytics per repo | ❌ | |

156| Email notifications | ❌ | in-app only |

157| Email digest | ❌ | |

158| Mobile PWA | 🟡 | responsive CSS, no manifest |

159| Native mobile apps | ❌ | |

160| Dark mode | ✅ | only mode |

161| Light-mode toggle | ❌ | |

162| Keyboard shortcuts | ✅ | `/shortcuts` page |

163| Command palette | 🟡 | Cmd+K → Ask AI, no generic palette |

164

165---

166

167## 3. BUILD PLAN (BLOCKS)

168

169Each block is a self-contained unit. Order matters for dependencies. Each block ends with tests + commit + push.

170

171### BLOCK A — Hardening the current surface

172Polish what's shipped before adding more. **Priority: do this first if parity gaps are minor.**

173- **A1** — Dark/light theme toggle (cookie, CSS variable swap)

174- **A2** — Audit log UI page (`/settings/audit` + `/:owner/:repo/settings/audit`)

175- **A3** — Reactions UI on issues / PRs / comments (data exists)

176- **A4** — Draft PR toggle + filter

177- **A5** — Issue + PR templates (`.github/*_TEMPLATE.md` auto-prefill)

178- **A6** — Saved replies per user

179- **A7** — Environments + deployment history UI (`deployments` table)

180- **A8** — Email notifications (opt-in, SMTP via env)

181

182### BLOCK B — Identity + orgs

183- **B1** — Organizations (schema: `organizations`, `org_members`, `teams`, `team_members`)

184- **B2** — Repos owned by orgs (nullable `repositories.orgId`)

185- **B3** — Team-based CODEOWNERS (`@org/team` resolution)

186- **B4** — 2FA / TOTP (enroll, recovery codes)

187- **B5** — WebAuthn / passkeys

188- **B6** — OAuth 2.0 provider (third-party apps can request access)

189

190### BLOCK C — Runtime + hosting

191- **C1** — Actions-equivalent workflow runner

192 - Workflow YAML parser (`.gluecron/workflows/*.yml`)

193 - Job queue + worker pool (Bun subprocesses)

194 - Artifact storage + log streaming

195 - Integrates with gates

196- **C2** — Package registry (npm + container protocol)

197- **C3** — Pages / static hosting (`gh-pages` branch → served at `<owner>.<repo>.pages.gluecron.com`)

198- **C4** — Environments (prod/staging/preview) with protected approvals

199

200### BLOCK D — AI-native differentiation

201This is where GlueCron beats GitHub outright. **Priority: ship these loud.**

202- **D1** — Semantic code search (pgvector + Claude embeddings)

203- **D2** — AI dependency updater (reads lockfile, opens PRs, verifies green)

204- **D3** — AI PR triage agent (auto-assigns reviewers, labels, milestones)

205- **D4** — AI incident responder (on deploy failure, opens issue with root cause)

206- **D5** — AI code reviewer that blocks merges (enforced via branch protection "AI approval required")

207- **D6** — AI "explain this codebase" on repo landing (auto-generated, cached)

208- **D7** — AI changelog for every commit range (`/:owner/:repo/ai/changelog?from=...&to=...`)

209- **D8** — AI-generated test suite (reads public API, generates failing tests)

210- **D9** — Copilot-style completion endpoint for IDE plugins

211

212### BLOCK E — Collaboration parity

213- **E1** — Projects / kanban boards (`projects`, `project_items`, `project_fields`)

214- **E2** — Discussions (forum threads per repo)

215- **E3** — Wikis (git-backed, separate bare repo per repo)

216- **E4** — Gists (user-owned tiny repos)

217- **E5** — Merge queues (serialised merge with re-test)

218- **E6** — Required status checks matrix (multiple named checks per branch protection rule)

219- **E7** — Protected tags

220

221### BLOCK F — Observability + admin

222- **F1** — Traffic analytics per repo (views, clones, unique visitors)

223- **F2** — Org-wide insights (green rate across all repos)

224- **F3** — Admin / superuser panel (user moderation, repo audit)

225- **F4** — Billing + quotas (storage, AI tokens, bandwidth)

226

227### BLOCK G — Mobile + client

228- **G1** — PWA manifest + service worker

229- **G2** — GraphQL API mirror of REST

230- **G3** — Official CLI (`gluecron` binary in Bun)

231- **G4** — VS Code extension

232

233### BLOCK H — Marketplace

234- **H1** — App marketplace (install third-party apps against a repo)

235- **H2** — GitHub Apps equivalent (bot identities with scoped permissions)

236

237---

238

239## 4. LOCKED BLOCKS (DO NOT UNDO)

240

241Everything below is committed, tested, and load-bearing. **Do not delete, rename, or semantically change without owner permission.**

242

243### 4.1 Infrastructure (locked)

244- `src/app.tsx` — route composition, middleware order, error handlers

245- `src/index.ts` — Bun server entry

246- `src/lib/config.ts` — env getters (late-binding)

247- `src/db/schema.ts` — 27 tables. New tables only via new migration.

248- `src/db/index.ts` — lazy proxy DB connection

249- `src/db/migrate.ts` — migration runner

250- `drizzle/0000_initial.sql`, `drizzle/0001_green_ecosystem.sql` — migrations

251

252### 4.2 Git layer (locked)

253- `src/git/repository.ts` — tree / blob / commits / diff / branches / blame / search / raw / tags / commitsBetween

254- `src/git/protocol.ts` — Smart HTTP pkt-line

255- `src/hooks/post-receive.ts` — CODEOWNERS sync, gates, auto-deploy, webhook fan-out

256

257### 4.3 Auth + security (locked)

258- `src/lib/auth.ts` — bcrypt, session tokens

259- `src/middleware/auth.ts` — softAuth + requireAuth

260- `src/middleware/rate-limit.ts` — fixed-window limiter

261- `src/middleware/request-context.ts` — request-ID

262- `src/lib/security-scan.ts` — `SECRET_PATTERNS` (exported) + `scanForSecrets` + `aiSecurityScan`

263- `src/lib/codeowners.ts` — parser + `ownersForPath` (last-match-wins)

264

265### 4.4 AI layer (locked)

266- `src/lib/ai-client.ts` — Anthropic client + model constants

267- `src/lib/ai-generators.ts` — commit / PR / changelog / issue-triage

268- `src/lib/ai-chat.ts` — conversational chat

269- `src/lib/ai-review.ts` — PR code review

270- `src/lib/auto-repair.ts` — worktree-backed repair commits

271- `src/lib/merge-resolver.ts` — AI merge conflict resolution

272

273### 4.5 Platform (locked)

274- `src/lib/notify.ts` — notification creation + audit log (swallow-failures pattern)

275- `src/lib/unread.ts` — unread count helper (never throws)

276- `src/lib/repo-bootstrap.ts` — green defaults on repo creation

277- `src/lib/gate.ts` — gate orchestration + persistence

278- `src/lib/cache.ts` — LRU cache, git-cache invalidation

279

280### 4.6 Routes (locked endpoints — behaviour must be preserved)

281- `src/routes/git.ts` — Smart HTTP (clone/push)

282- `src/routes/api.ts` — REST (`POST /api/repos`, `GET /api/users/:u/repos`, `GET /api/repos/:o/:n`, `POST /api/setup`)

283- `src/routes/auth.tsx` — register / login / logout

284- `src/routes/web.tsx` — home / new / browse / blob / commits / raw / blame / star / search / profile

285- `src/routes/issues.tsx` — issue CRUD + comments + labels + lock

286- `src/routes/pulls.tsx` — PR CRUD + review + merge + close

287- `src/routes/editor.tsx` — web file editor

288- `src/routes/compare.tsx` — base...head diff

289- `src/routes/settings.tsx` — profile + password

290- `src/routes/repo-settings.tsx` — repo settings + delete

291- `src/routes/webhooks.tsx` — webhook CRUD + test + `fireWebhooks`

292- `src/routes/fork.ts` — fork

293- `src/routes/explore.tsx` — discover

294- `src/routes/tokens.tsx` — personal access tokens

295- `src/routes/contributors.tsx` — contributor list

296- `src/routes/notifications.tsx` — inbox + unread API

297- `src/routes/dashboard.tsx` — authed home (`renderDashboard` exported)

298- `src/routes/ask.tsx` — global + repo AI chat + explain

299- `src/routes/releases.tsx` — tags + AI changelog

300- `src/routes/gates.tsx` — history + settings + branch protection UI

301- `src/routes/insights.tsx` — insights + milestones

302- `src/routes/search.tsx` — global search + `/shortcuts`

303- `src/routes/health.ts` — `/healthz` `/readyz` `/metrics`

304

305### 4.7 Views (locked contracts)

306- `src/views/layout.tsx` — `Layout` accepts `title`, `user`, `notificationCount`

308- Nav links: logo · search · Explore · Ask · Notifications · New · Profile (or Sign in / Register)

309- Keyboard chords: `/`, `Cmd+K`, `?`, `n`, `g d`, `g n`, `g e`, `g a`

310

311### 4.8 Tests (locked)

312- `src/__tests__/green-ecosystem.test.ts` — secret scanner, codeowners, AI fallback, health, rate-limit headers, `/shortcuts`, `/search`

313- All other existing test files — do not delete without owner permission

314

315### 4.9 Invariants (never break these)

316- `isAiAvailable()` guard returns true fallback strings when no ANTHROPIC_API_KEY. AI features degrade gracefully.

317- `getUnreadCount` never throws; returns 0 on any error.

318- Rate-limit middleware adds `X-RateLimit-Limit` + `X-RateLimit-Remaining` to every response, including 500s.

319- `c.header("X-Request-Id", ...)` set by request-context on every response.

320- Secret scanner skips binary/lock paths (`shouldSkipPath`).

321- `SECRET_PATTERNS` is an exported array. Its shape is `{ type, regex, severity }`.

322

323---

324

325## 5. OPERATIONAL NOTES

326

327### 5.1 Running locally

328```bash

329bun install

330bun dev # hot reload

331bun test # 76 tests currently pass

332bun run db:migrate

333```

334

335### 5.2 Environment

336- `DATABASE_URL` — Neon Postgres

337- `ANTHROPIC_API_KEY` — unlocks AI features

338- `GIT_REPOS_PATH` — default `./repos`

339- `PORT` — default 3000

340

341### 5.3 Models

342- `claude-sonnet-4-20250514` — code review, security, chat

343- `claude-haiku-4-5-20251001` — commit messages, summaries, light tasks

344- Swap via `MODEL_SONNET` / `MODEL_HAIKU` constants in `src/lib/ai-client.ts`

345

346### 5.4 Deployment

347- `railway.toml` / `fly.toml` present

348- Crontech deploy on green push to default branch (can opt out via `autoDeployEnabled`)

349

350---

351

352## 6. SESSION WORKFLOW (WHAT THE NEXT AGENT DOES)

353

3541. Read this file, `CLAUDE.md`, `README.md`, `git log -1 --stat`.

3552. Check `git status` + current branch.

3563. Pick the next unfinished block from §3 (lowest letter + number first, unless owner specifies).

3574. Create a todo list that mirrors the sub-items of that block.

3585. Build. Write tests. Run `bun test`.

3596. Commit with `feat(<BLOCK-ID>): ...`.

3607. Push.

3618. Update this file:

362 - Move the block's row in §2 to ✅ where applicable.

363 - Add the block's files to §4 LOCKED BLOCKS.

364 - Commit + push again.

3659. Start the next block. **Do not stop to ask.**

366

367If a block is too large for a single session, split it into a sub-plan at the top of the session, ship what you can, and document what's left at the end of this file under a `## 7. IN-FLIGHT` section.

368

369---

370

371## 7. IN-FLIGHT

372

373(Intentionally empty. Add here if a block is partially complete at session end.)

ModifiedCLAUDE.md+13−0View fileUnified Split

@@ -2,6 +2,19 @@

33AI-native code intelligence platform — git hosting, automated CI, and green ecosystem enforcement.

5## READ FIRST — every session

7**`BUILD_BIBLE.md` is mandatory reading for every Claude agent before any code changes.**

9It contains:

10- Agent policy (do-not-undo rule, continuous-build rule)

11- GitHub parity scorecard (what's shipped vs missing)

12- Numbered build plan (Blocks A–H)

13- Locked components that cannot be altered without owner permission

14- Session workflow

16Do not skip it. Do not refactor locked files. Do not stop mid-block.

518## Stack

619

720- **Runtime:** Bun

821