Orbit

The design system added expandable entry stories (PR #31) for history, PRs, and issues. This wires the Go side: entryRow gains Body, StoryID, and DesignHref fields, the project handler populates them from issue/PR bodies and PR lookups for history entries, and the template uses a shared entryrow partial that renders expandable rows when a body is present.

CSS and JS in web/static updated to match the design system.

See on code.bas.es →

History entries, pull requests, and issues on the project detail page are single-line rows with no way to see the full description. Clicking an entry now expands it to show the body text below, aligned to the title column.

The approach avoids nesting inside CSS grid (which caused subgrid alignment issues). Instead, expandable rows are plain .entry-row elements with a sibling div for the body. A small JS click handler toggles visibility. The dot pulses on hover as an affordance, matching the home page project rows.

PRs and issues include a "See on code.bas.es" link in the expanded body. History entries show the PR description.

Design system only — no Go changes yet. Implementation will follow.

See on code.bas.es →

Summary

• Fix migration crash on production: existing duplicate (project_id, pr_number) rows from webhook redelivery prevented CREATE UNIQUE INDEX
• Dedup step keeps the oldest row per pair before creating the index

Test plan

• [x] All tests pass (go test ./...)
• [x] Deployed to production — service started successfully, backfilled 3 entries

🤖 Generated with Claude Code

See on code.bas.es →

The back-link from design system preview pages points to /projects/{slug}/ with a trailing slash. The project route only matches without one, so the link 404s. This adds a redirect from the trailing-slash variant to the canonical URL.

Closes #27

See on code.bas.es →

Throwaway PR to inspect Forgejo merge webhook action

See on code.bas.es →

Summary

• Make the periodic sync resilient by backfilling history entries for merged PRs missed by webhooks (late webhook setup, downtime, network issues)
• Add UNIQUE(project_id, pr_number) constraint to history_entries so both webhooks and sync are idempotent
• New ListMergedPRsWithoutHistory query finds gaps; BackfillHistory syncer method fills them at startup and every 15 minutes

Closes idea #3

Test plan

• [x] TestCreateHistoryEntryIdempotent — duplicate insert returns (nil, nil), no error, one row
• [x] TestListMergedPRsWithoutHistory — merged without history returned, merged with history excluded, open excluded
• [x] TestBackfillHistory — end-to-end: sync merged PR, backfill creates entry, second run is idempotent
• [x] All existing tests pass (go test ./...)

🤖 Generated with Claude Code

See on code.bas.es →

The three-state dot logic (muted/active/done) from PR #25 had no unit tests. This adds table-driven tests covering all state transitions: stale projects always muted, active projects with open issues or non-draft PRs show orange, draft-only or no open work shows green.

See on code.bas.es →

Project dots on the home page were binary: orange or grey. This doesn't distinguish a project with open work from one that's caught up.

Projects now show three dot states:

• Green (done): active within 7 days, no open issues or PRs
• Orange (active): active within 7 days, has open issues or PRs
• Grey (muted): no activity for over a week

The project detail page also gets a dot next to the project name, using the same logic.

Also adds "back to orbit" links from the styleguide pages and fixes the trailing-slash redirect on the preview handler so relative links resolve correctly. Updates the scaffold templates with matching back-links.

See on code.bas.es →

The scaffold templates used by init_design had no way to navigate back to the orbit project page. Added relative "orbit" links to both the styleguide index and the preview breadcrumb so users can get back to the project.

Only affects newly scaffolded projects. Existing projects need a separate update during a session.

See on code.bas.es →

The project detail page always showed the "design system" link in the header, even for projects with no styleguide directory. Clicking it returned a 404.

The link is now gated on HasDesign, which is true when the project's source can resolve its styleguide directory. Projects without one no longer show a broken link.

See on code.bas.es →

Orbit's CLAUDE.md was entirely hand-written. The arne/conventions repo now manages shared rules (git workflow, PR/issue conventions, spec flow, styleguide protection) via apply.sh, which writes generated content between markers in CLAUDE.md and places reference docs in docs/conventions/.

This adds a conventions.yaml declaring orbit's layers (orbit, orbit-design, systemd-service), runs apply.sh to generate the managed block, and trims the hand-written section to just deployment and source layout — the only orbit-application-specific content.

Also fixes the design-session hook regex to allow hyphenated layer names like orbit-design/, and registers arne/conventions as a project in orbit.

Closes #21

See on code.bas.es →

Design specs in the Design stage always glowed sodium because designs.File had no modification time — the web handler passed Active: true unconditionally.

This adds a ModTime field to designs.File, populated from os.Stat in LocalSource and from the Forgejo contents API's last_modified field in ForgejoSource. The project handler now computes Active via isActive(f.ModTime), the same 7-day window rule used for every other flow item.

Closes #6

See on code.bas.es →

The home-page template hard-coded arne/ as the owner prefix in every project row. The owner is already available on the web handler via ORBIT_FORGEJO_OWNER, so this threads it through to the template via a small view struct.

Closes #8

See on code.bas.es →

PR #14 settled how pull request titles and descriptions should read, but issues were left unexamined. The current open backlog makes the gap concrete: every one of the four open issues uses an area prefix (design-system:, web:, project-detail:) followed by a telegraphic description that barely stands on its own as a sentence. That's exactly the pattern we moved away from for PRs, and for the same reason — the prefix is tagging noise a human reading the title doesn't need, and the Forgejo label system already handles area categorization better.

This PR extends CLAUDE.md with an Issue titles and descriptions subsection that applies the same discipline (active voice, plain English, no area prefixes) with one deliberate difference: tense. PR titles describe work done, issues describe work needed. The doc also calls out that issues are seeds, not specs — prose over bullets, a Scope section to bound what closing the issue looks like, and no pretense of being a specification.

Follow-ups

• Rewrite the four open orbit issues (and the single closed one, #7) to match the new convention. This is the parallel of the historical-PR rewrite that followed the PR convention doc.
• Add a history entry recording the issue rewrite once it's done.

See on code.bas.es →

While finishing up PR #15 (the merge-history-on-edit bug fix) a follow-up question came up: what action string does Forgejo actually fire for a merge webhook? The test in PR #15 assumes "closed", matching GitHub convention, but the only way to be confident was to observe it directly.

To observe it, a throwaway PR #16 with an empty .webhook-probe file was opened and merged. The DEBUG log added temporarily to handlePREvent confirmed Forgejo fires action="closed" merged=true on merge — so the guard in PR #15 is correct. But merging #16 landed the empty .webhook-probe file on main as a side effect.

This PR removes the file. One line of diff, no code changes, no test changes. The diagnostic logging was never committed.

Why PR #15's merge didn't create a history entry

Worth recording this since it explains a visible gap in orbit's history stage. PR #15 was merged at 20:18:16, and the deploy sequence that followed (go build && install && systemctl restart) restarted orbit's systemd service at 20:18:17 — almost exactly when Forgejo was trying to deliver the merge webhook. The delivery landed in the ~1-second restart window and was either refused by Caddy or silently dropped; Forgejo did not retry successfully.

The PR row for #15 exists in the pull_requests table because the periodic sync running on startup backfilled it from Forgejo's API. But the periodic sync only upserts PR rows — it does not create history entries. History entries are webhook-only, and the webhook was lost. The history entry for PR #15 will be inserted manually via SQL as part of this cleanup.

Lesson: avoid restarting orbit immediately after merging a PR that it webhooks into. Separate the operations by at least a few seconds so the webhook has time to land.

See on code.bas.es →

The PR dispatch in handleWebhook used to fire handlePRMerge whenever pr.Merged was true, without checking the webhook action. A merged PR stays merged=true forever, so any subsequent webhook event on it — a title change, a body edit, a label tweak, a comment — would re-fire the handler and insert another history row for the same merge.

We noticed this while rewriting historical PR titles via the Forgejo API: each PATCH to a merged PR triggered an edited webhook, which produced a duplicate history entry. Seven PRs ended up with fourteen spurious rows in orbit's live DB before the pattern was clear. The duplicates were cleaned up manually via SQL, but the underlying bug remained.

The fix

One-line guard on the dispatch. Require action == "closed" alongside pr.Merged, so the handler runs only on the actual merge event:

if payload.Action == "closed" && payload.PullRequest.Merged {
    s.handlePRMerge(project, payload.PullRequest)
}

The PR row itself still updates via handlePREvent on every webhook delivery — that runs unconditionally and is idempotent by design, so PR metadata in the store stays in sync with Forgejo regardless of which action fired.

Regression test

TestWebhookPR_EditedAfterMerge in api/webhooks_test.go exercises the bug directly: merge a PR, assert one history entry exists, send a follow-up edited webhook on the same (still-merged) PR, assert the history entry count is still one. The test also verifies the PR row picked up the edit via handlePREvent — so we're confirming the fix doesn't over-correct and suppress legitimate state updates.

Follow-ups

None. The fix is surgical and the test covers the exact scenario that produced the duplicates.

See on code.bas.es →

The repo's git conventions in CLAUDE.md encouraged conventional-commit prefixes (feat:, fix:, chore:) on PR titles, but as orbit has grown those prefixes have started reading as clutter — they add technical noise without telling a reader anything about what actually changed. The History stage on orbit itself makes this concrete: a row that says feat: pull request tracking and Claude removal is worse to scan than one that says Show open pull requests in the Review stage.

This PR drops the prefix guidance and adds a short section covering title and description structure. Titles should describe what orbit can do now, active voice, plain English. Descriptions should open with the problem, use subheadings for bundled concerns, and keep scope-boundary notes (Known cuts, Follow-ups) at the bottom.

No code changes, no behavior changes. Documentation-only, so the convention is in the repo before the backlog of older PRs gets rewritten by hand to match.

Follow-ups

• Rewrite titles and descriptions on the previously-merged PRs (Orbit MVP through #13) to serve as in-repo examples of the new convention.
• Normalize commit author email on the three commits made from local git config (arnefismen@gmail.com → arne@fismen.net) during the rewrite.
• Consider a semantic taxonomy later (labels, History stage categories) once a few more PRs have landed under the new convention.

See on code.bas.es →

The Review stage on every project page has been empty since #5 because orbit had no concept of pull requests. This PR adds the full tracking stack: a new pull_requests table mirroring the issue table's shape, webhook updates on every PR lifecycle event (opened, edited, closed, reopened), periodic sync as a safety net for dropped webhook deliveries, and handler logic that populates the Review stage with open non-draft PRs sorted by activity. Draft PRs are tracked but hidden — they become visible the moment the draft flag flips.

PR activity also factors into the home page's project-row dot state: a project with a recent PR but no other movement now glows sodium instead of sitting quiet.

Claude removal

The claude package is gone entirely. Its only job was summarizing PR diffs into history entry text on merge, but the summaries were verbose and often read worse than the PR title they replaced. The merge handler now stores pr.Title verbatim as the history entry's summary. The trade is automation for discipline: write good PR titles and descriptions, and the History stage reads well for free.

Full audit: claude/ package deleted, import chain cleaned through main.go, api/api.go, api/webhooks.go, and config.go, ORBIT_CLAUDE_API_KEY env variable retired, forgejo.GetPullRequestDiff (orphaned after the removal) also deleted. The historySummary helper in the web layer used to prepend PR #N: to entries with a PR number attached; that prefix is gone too, matching the new "lean on the PR title" posture.

Scope expansion: sync tests

sync.go was untested before this PR. Adding the new PR sync was an opportunity to lock in the existing issue sync's behavior with tests, so sync_test.go covers both paths — 4 issue sync cases and 4 PR sync cases. Any future regression in the shared sync infrastructure will now be caught by the suite.

Follow-ups

• Expand-on-click UI for PR bodies — the body field is stored, the UI is a separate spec.
• Deleted-on-Forgejo PR reconciliation — rare edge case, manual cleanup for now.
• Review metadata (approved / changes-requested badges) if they prove useful.
• Stacked PR / branch graph visualization using base_ref and head_ref fields.

Closes arne/orbit#7.

See on code.bas.es →

Finished design specs used to linger in the Design stage forever — the spec would stay visible even after its implementation had shipped. This PR makes them archive automatically: add a Finalizes: 2026-04-05-foo.md line to a PR's body, and when you create the PR, orbit's webhook handler deletes the spec file from the PR branch via the Forgejo contents API. The deletion becomes part of the feature PR's diff, so the spec disappears atomically with the work that finalized it.

Deletion, not a move to docs/archive

Git is already the archive — every byte is retrievable via git log --follow or Forgejo's commit browser forever. A second on-disk location would be redundant maintenance.

Orbit-side, not AI-side

The design-folder guardrail (#2) blocks Claude from editing design/ outside a design session, but the guardrail only applies to Claude Code tool calls. Orbit-the-server running in systemd calls the Forgejo API directly and sidesteps the hook entirely. The guardrail stays unmodified.

Convention

A line in the PR body starting with Finalizes: (case-insensitive), then one or more comma-separated spec references. Accepts bare filenames (foo.md), specs/foo.md, or design/specs/foo.md — all normalize to design/specs/<basename>. Basenames are validated against ^[A-Za-z0-9._-]+\.md$ to reject path traversal attempts and unexpected extensions.

Also

Filters README.md out of the Design stage at the designs.Source boundary — the scaffold's placeholder was cluttering the list.

Known cuts

• No edited/synchronize action handling; only opened. To add a Finalizes: line after the PR exists, close and reopen.
• No git blob fallback for deleted specs in the design-preview route — once gone from HEAD, the preview 404s on that path. Forgejo's commit browser remains the retrieval path.
• Label-based triggers are deliberately out of scope. PR body only.

See on code.bas.es →

PR #4 committed to orbit's visual direction in design/ but left the live web layer on its MVP-era generic styles. This PR ports the styleguide into production: web/static/orbit.css is now the design system, web/templates/* render with the new components, and both pages reflect the new flow-based structure.

Home page

A single column of .project-row entries ordered by last-activity descending. Each row shows the project slug and name, a one-line summary of the most recent history entry, and a relative time (3h, 2d, 1w). The leading dot glows sodium if the project moved within the last 7 days, muted grey otherwise.

Project detail page

Five flow sections — Ideas, Design, Build, Review, History — with the mapping specified in #4's spec. Empty stages collapse. History is grouped by calendar day with .day-divider headers, and entries beyond the first 12 collapse into a <details class="entry-expand"> with show N earlier entries as the summary.

Activity helpers

New web/activity.go module exposes ActiveWindow, isActive(t time.Time), and projectLastActivity(project, ideas, issues, history). The latter aggregates timestamps across all child entities so a project's dot state reflects its most recent movement across any flow domain.

Font loading

Iosevka .woff2 files vendored under web/static/fonts/ and loaded via <link rel="preload"> in web/templates/layout.html, matching the design spec's FOUT-elimination approach.

Also: UTC timestamp bugfix

While evaluating this PR live against the production orbit instance we hit a latent sync bug: sync.go and api/webhooks.go were calling time.Parse(time.RFC3339, ...) which returns a time.Time with a fixed-offset zone. The modernc.org/sqlite driver serializes those via Time.String() (producing "2026-04-05 13:11:46 +0200 +0200") and then cannot scan them back into time.Time. Store tests passed because they used .UTC(), but production data was unreadable once the new home and project handlers started reading Issue.ForgejoUpdatedAt for the activity rule.

Fixed at the store boundary in UpsertIssue: every forgejoUpdatedAt is normalized with .UTC() before hitting the driver. The fix is bundled into this PR because it blocked live evaluation.

Known cuts

Per-issue triage between Ideas/Design/Build stages (no schema yet), open-PR tracking for the Review stage (addressed in #13), and design-spec last-activity from file mtime (designs.File doesn't expose one) — all deferred to follow-up work.

See on code.bas.es →

Orbit's MVP rendered with browser-default system-ui and a handful of ad-hoc styles. That was fine for getting the data flowing but gave orbit no aesthetic identity — no sense of what a glance at the project page should feel like. This PR commits to a coherent visual direction that scales from atoms to pages without rework.

The guiding principle: orbit should take little space and let the content it holds — projects, ideas, issues, specs — do the showing off. Every choice falls out of that.

Palette

Warm near-black background with warm cream text, a single sodium-orange accent for interaction and active state. Everything else is warm greys. Dark by default, light theme via prefers-color-scheme only — no manual toggle to clutter the chrome.

Typography

Iosevka carries everything — headings, body, labels, code. One instrument, one font. Its narrow proportions are the most literal answer to "takes little space". Self-hosted from design/fonts/ (woff2, weights 400 and 700, SIL OFL). Font loading uses <link rel="preload"> plus font-display: block to eliminate the flash-of-unstyled-text.

Brand

A single sodium-orange dot. No wordmark — the word "Orbit" already appears in the text whenever orbit introduces itself, so the brand mark is pure graphic.

Dot vocabulary

Three tones carry a universal status language. Active (sodium) for flow items that moved within the last 7 days. Stale (warm grey) for flow items that haven't. Done (muted sage) for every entry in the History archive. Flow items decay with time; history is terminal and uniform. The rule is implemented server-side via a single isActive(t) helper plus an ActiveWindow = 7 * 24 * time.Hour constant.

Component inventory

.site-header, .section-heading, .project-row, .entry-row, .entry-list, .entry-expand, .meta-strip, .day-divider, plus the existing .brand, .dot, .dot-active, .dot-done, .btn atoms. CSS subgrid keeps entry-row columns aligned across variable label widths.

Project detail page

Flow-based stage model: Ideas → Design → Build → Review → History. Every item lives in one stage at a time. Empty stages collapse. Raw ideas and untriaged issues sit in Ideas; developing ideas and in-progress specs sit in Design; ready-to-ship work sits in Build; open PRs sit in Review; merged PRs and completed events sit in History.

The spec at design/specs/2026-04-05-orbit-design-system.md is the canonical reference.

Known cuts

This PR ships the styleguide under design/ and page previews only. Porting to web/static/orbit.css and web/templates/*.html is a deliberate follow-up so the system can be lived-with-in-isolation first.

See on code.bas.es →

The original init_design MCP tool produced a three-file scaffold (one HTML, one CSS, one markdown spec) that conflated file structure with visual design choices. Every project that called the tool inherited a specific palette, typography, and layout system, whether that fit the project or not. The tool needed to teach conventions — folder layout, file naming, the separation between styleguide and page previews — without committing to an aesthetic.

This PR rewrites the scaffold to be structural. The output is a folder tree under design/ with named sub-folders for specs/, preview/, components/, and fonts/, a single style.css organized into banner- commented bands (tokens / reset / elements / forms / components / prototype chrome), a theme.js placeholder, and README files explaining each location. No opinionated colors, typography, or component shapes — just the structure.

Prototype chrome namespace

Styleguide-only UI (breadcrumbs, section wrappers, nav chrome for page previews) lives under a .prototype-* class namespace so downstream porting to a real web layer knows what to keep and what to strip. When a real design system later builds on top of this scaffold, the prototype chrome can stay in design/ and get omitted from the ported CSS.

Page previews as navigation

The scaffold includes design/preview/index.html as the canonical entry point for interactive previews, with a .prototype-breadcrumb for navigating between preview pages. Real dev chrome, not part of any page being previewed.

Tests

mcp/scaffold_test.go asserts the exact folder layout and file list so the scaffold contract is pinned against regressions.

See on code.bas.es →

As orbit grew and design/ became the canonical styleguide the web layer would be ported from, accidental AI edits to those files during unrelated feature work became a real risk. One thoughtless rewrite of design/style.css during a Go refactor would silently desync the styleguide from the web layer.

This PR installs a PreToolUse hook (.claude/hooks/design-session-guard.sh) that enforces a two-mode rule: design work and feature work are strictly separated. In normal mode, Edit, Write, MultiEdit, and Bash operations under design/ are blocked. To work on the styleguide, the user creates a session marker file (.claude/design-session-active) from a separate terminal outside Claude Code. While the marker is present, design/ is unlocked — and symmetrically, everything else is locked so feature work can't leak in during a design session.

The hook is deliberately AI-unreachable in every direction: Claude cannot create, delete, read, or otherwise manipulate the marker file via any tool, because the whole point of a mode flip is that the human makes it.

Detection

For Edit/Write/MultiEdit, the hook compares the resolved absolute path against the repo root and classifies writes as in-design or out-of-design. For Bash, it uses a path-token regex — (^|[^[:alnum:]_])design/ — that matches design/, ./design/, /design/ and quoted variants, but deliberately does not match designs/ (the Go package) or redesign/.

Reads are always allowed

The hook never blocks reading from design/. Claude can reference the styleguide for context at any time, from any mode.

See on code.bas.es →

Previewing design files through orbit's web dashboard required committing and pushing to Forgejo for every change, then waiting for the API cache to catch up before the preview reflected the update. That's a slow loop when you're iterating on a stylesheet or a markdown spec.

This PR points orbit at the local working-tree checkout for design reads, with the Forgejo API as a fallback when the checkout is unavailable. Set ORBIT_SOURCE_ROOT to the directory containing your repo checkouts (e.g., ~/source), and orbit resolves {sourceRoot}/{owner}/{slug}/design/ for each registered project. Unset it to fall back to Forgejo-only reads.

The designs package

New designs.Source interface with three implementations. LocalSource reads from the working tree and has traversal and symlink-escape guards — it resolves symlinks and re-validates containment before reading to close the TOCTOU window. ForgejoSource wraps the existing forgejo.Client. ChainSource composes them, trying each in order and falling through on ErrNotFound.

Web and API handlers now depend on the Source interface rather than calling forgejo.Client directly for design reads. Production wiring in main.go composes a ChainSource of LocalSource + ForgejoSource so local wins when present.

Security

The design-preview route enforces an extension allowlist (HTML, CSS, JS, images, fonts, markdown, text — 15 types total). Unsupported extensions return 415. Every design response carries Cache-Control: no-store to prevent any layer from caching stale content while iterating.

Also

Adds CLAUDE.md with the repo conventions that will grow alongside the codebase: squash-merge policy, deployment notes, source layout.

See on code.bas.es →