Files

T

Ben Stull 29c96ea300 Release 0.2.0: graduation merge race fix + VITE_APP_NAME + versioning infrastructure

- Fix §13.3 step 4 race against Gitea's async mergeability
  computation: gitea.wait_for_mergeable polls the mergeable
  field before calling merge, and bot._merge_with_retry rides
  out the transient 'Please try again later' response.
- Frontend now requires VITE_APP_NAME at build time
  (frontend/vite.config.js fails the build if unset). Header
  brand, landing H1, and browser title read the deployment's
  configured name.
- Establish framework versioning: VERSION (canonical) +
  frontend/package.json#version mirror; CHANGELOG.md as the
  release log with RFC 2119 / 8174 normative-language
  upgrade-steps; SPEC.md §20 as the binding policy; CLAUDE.md
  capturing the separation-of-concerns rule; docs/DEPLOYMENTS.md
  as the downstream operating manual; docs/QUICKSTART-VISION.md
  staking the future one-command-deploy capability.
- Surgical fix to SPEC.md opening so the spec no longer asserts
  OHM is the corpus the framework produces.
- SPEC.md §19.2 gains the 'Deployment-supplied subject framing'
  candidate that drives the 0.3.0 release.

2026-05-26 06:37:48 -07:00

3.3 KiB

Raw Permalink Blame History

Working in rfc-app

This is the framework — the software that hosts an RFC standardization process. It is intended to power multiple deployments, each of which brands and configures itself independently. The framework is the substrate; the deployment is the instance.

The separation-of-concerns rule

Code in this repo must never bake in values that belong to a specific deployment. That includes:

The deployment's display name, tagline, or pitch copy.
The corpus or domain the deployment is about.
The deployment's URL, organization name, branding assets.
Any reference to the people or community running a specific instance.

When a value of that kind is needed in source, it goes behind configuration — typically a build-time VITE_* env var the frontend reads, or a backend env var the API surfaces. The framework supplies a loud failure path (e.g. build fails, server refuses to start) when a required value is missing, so a misconfigured deployment can't ship the wrong content silently.

The framework name itself (Wiggleverse RFC, per the founding documents) does appear in source — in the chat system prompt, in PHILOSOPHY.md, in SPEC.md. That is correct: those references are about the framework, not about any deployment. Deployment names and deployment content stay out.

If you find a hardcoded deployment-specific string in source, treat it as a bug to fix in the framework: make it configurable, document the new env var in frontend/.env.example or backend/.env.example, and bump the version per the rules below.

Versioning

The binding policy is in SPEC.md §20. Summary so working sessions don't have to reload the full section:

The VERSION file at the repo root is the canonical version; frontend/package.json#version mirrors it. A divergence between the two is a spec-level bug.
SemVer: patch = no operator action required; minor = new functionality plus, while pre-1.0, breaking changes spelled out in the changelog; major = reserved for the first stable cut and afterwards for breaking changes.
Every release adds an entry to CHANGELOG.md. Breaking entries carry an "upgrade steps" block; a downstream deployment must be able to upgrade from any prior version by walking those blocks in order.

The practical recipe for downstream projects — how to pin, how to upgrade, how the two-repo loop runs — is in docs/DEPLOYMENTS.md. Don't restate that recipe here; if it's wrong, fix it there.

How changes typically flow in

The framework receives change requests from deployments. The intake loop:

A deployment operator notices something they want different (different name, missing feature, wrong behavior).
Triage: is this a framework concern (bug, missing affordance, hard- coded value that should be configurable) or a deployment concern (just a config value to change)?
If framework: implement here, bump the version, update the changelog with upgrade steps.
The deployment then pins to the new version and applies any required config changes.

The framework does not name specific deployments, but it does aim to make each deployment's upgrade path obvious and mechanical.

Code layout

See docs/DEV.md for the slicing plan and build history. See SPEC.md for the binding contract — section numbers (§n.n) in the codebase refer to that file.