feedBack/.specify/memory/constitution.md

# FeedBack Constitution

> FeedBack is a self-hosted, single-user web app for browsing, playing, and
> practicing interactive music notation, built around its own open `.sloppak`
> chart format (charts imported from Guitar Pro / MusicXML or authored in the
> built-in editor). This constitution captures the non-negotiable principles
> that govern its core (`server.py`, `lib/`, `static/`) and that all in-tree
> plugins (`plugins/<name>/`) inherit by default. It is a *retrospective*
> document — the codebase came first, the principles below were distilled from
> `CLAUDE.md`, `README.md`, and the shape of the existing implementation.

## Core Principles

### I. Self-Hosted, Single-User, Docker-First

FeedBack targets one user running one container against a personal
song library folder. There is no multi-tenant model, no
authentication, no rate limiting, and no shared backend. Deployment is
expressed as a single `docker compose up -d` against the bundled
`Dockerfile`; everything required (vgmstream, FFmpeg, FluidSynth,
Python) is baked into the image so the host machine needs
only Docker. Native (non-Docker) launch is supported for development
but not the primary supported path.

**Non-negotiable rules**

- Do not introduce a user/account model, multi-tenant data partitioning,
  or auth middleware. All endpoints assume one trusted local user.
- New runtime dependencies (binaries, Python modules) must be installable
  inside the existing `Dockerfile`. If something cannot run in the
  container, it does not ship in core.
- `DLC_DIR` and `CONFIG_DIR` are the only required configuration inputs.
  Adding a new mandatory path/env var is a constitutional change.

### II. Vanilla Frontend — No Frameworks

The frontend (`static/app.js`, `static/highway.js`, `static/v3/index.html`,
`static/style.css`) is plain JavaScript with the `fetch` API, direct DOM
manipulation, and the Canvas 2D / WebGL2 APIs. The only style framework
is Tailwind CSS, served as a prebuilt static stylesheet
(`static/tailwind.min.css`, regenerated by `scripts/build-tailwind.sh`)
— never the runtime Play CDN, whose on-the-fly JIT rescans the DOM on
the main thread and caused sustained frame drops with the 3D highway
(feedBack-desktop#110). No React, Vue, Svelte, bundler, transpiler, or
TypeScript appears in the core static tree, and no build step runs on
the serve path: the Tailwind build is a maintainer-only one-shot whose
output is committed, so Docker / desktop / end users never build. New
features extend `app.js` and the existing globals (`window.playSong`,
`window.showScreen`, `window.createHighway`, `window.feedBack`).

Native ES modules are a first-class, build-free extension mechanism.
Because `<script type="module">` and `import` are browser features — not
a bundler — a large source file MAY be split into an `import`-ed module
graph of plain source files, with **no build step and no framework**. A
plugin opts in with `"scriptType": "module"` in `plugin.json`: its
`screen.js` becomes a one-line `import './src/main.js'`, and the host
serves the `src/` subtree from the sandboxed `/api/plugins/<id>/src/…`
route and injects the entry as `<script type="module">`. The classic
global-scope `screen.js` path remains fully supported; both coexist, and
module scripts are still source-served — the no-bundler, no-transpiler,
build-free-at-serve rule is unchanged. Core's own `static/` tree may
migrate to the same module-graph shape (`static/js/…`) over time under
this rule.

**Non-negotiable rules**

- Do not introduce a frontend framework, JSX, or a JS build pipeline in
  core. Plugins MAY ship their own bundled assets but core MUST remain
  source-served.
- ES-module plugins remain source-served: no bundler or transpiler, and
  their own asset URLs (worklets, WASM, images) resolve via
  `import.meta.url` — never `document.currentScript`, which is `null`
  inside a module. `scriptType:"module"` and the optional `minHost`
  version floor are the only new `plugin.json` keys the module path adds.
- Because the core Tailwind stylesheet is prebuilt, it contains only the
  classes present in core source at build time. Core's committed
  `static/tailwind.min.css` MUST stay in sync with source — CI enforces
  this by rebuilding and diffing. A plugin that uses Tailwind classes
  not guaranteed in core (notably arbitrary values like `w-[37px]`)
  MUST ship its own compiled stylesheet via the `styles` capability,
  built with `corePlugins.preflight = false` so it emits only utilities
  and does not re-apply the base reset core already provides. Plugins
  MUST NOT load the Tailwind Play CDN (or any runtime CSS JIT) — the
  same no-CDN, build-free-at-serve rule that binds core binds plugins.
- New UI state lives in `localStorage` (or a backend endpoint), not in a
  framework store.
- Naming: camelCase JS, kebab-case CSS, snake_case plugin IDs. Player
  layout invariants (`#player` flex-column, `#highway` flex:1,
  `#player-controls` at the bottom) MUST be preserved.

### III. Plugins Are the Extension Point — Isolated by `load_sibling`

Functionality that is not part of the irreducible "browse + play charts"
loop ships as a plugin under `plugins/<name>/`, not as core code. Each
plugin is its own directory (typically a separate git repo), discovered
at startup via `plugin.json`, and free to add nav links, screens,
settings panels, and `/api/plugins/<id>/...` routes. Plugins MUST
isolate their backend Python imports via `context["load_sibling"]` so
two plugins shipping a generic `extractor.py` / `util.py` / `client.py`
do not collide in `sys.modules`.

**Non-negotiable rules**

- Generic features (practice journal, setlist, metronome, tone player,
  tab view, MIDI control, stem mixing, editors, etc.) belong in a plugin
  repo, not in `lib/` or `server.py`.
- Plugin backend modules MUST use `context["load_sibling"]("name")` for
  sibling imports. Bare `import sibling` works during transition but
  triggers a startup warning when a name collides.
- Plugins MUST register routes under `/api/plugins/<plugin_id>/...`,
  use `window.feedBack.emit/on` for cross-plugin communication, and
  prefix their `localStorage` keys with their plugin id.
- Plugins inherit this constitution and may layer additional rules in
  their own `CLAUDE.md`, but MUST NOT relax core principles (e.g. a
  plugin cannot require a frontend framework in core).

### IV. Backwards-Compatible Chart Library

The whole point of FeedBack is that a user points it at an existing
song library folder and it Just Works. The library is scanned and
indexed in `meta.db` (SQLite via `MetadataDB`). The open Sloppak
format (`lib/sloppak.py`; specified at
[got-feedback/feedback-feedpak-spec](https://github.com/got-feedback/feedback-feedpak-spec),
published as feedpak — same format) is the preferred
format and the home for new features; loose-folder XML charts
(`lib/loosefolder.py`) are also discovered and played as a first-class
format. Both must keep playing across releases.

**Non-negotiable rules**

- Never modify, move, or delete files inside the user's library folder
  without an explicit user-initiated action (retune, edit metadata).
- A library scan MUST be non-blocking: the user can browse already-
  scanned songs while import continues. Scans MUST tolerate corrupt or
  partial files without aborting the batch.
- Schema migrations on `meta.db` MUST be additive and idempotent;
  unrecognized columns from a newer build MUST not crash an older one.
- Existing arrangement IDs, sloppak manifests, and the highway
  WebSocket message shape are stable contracts. Breaking changes
  require a CHANGELOG entry under "Migration notes".

### V. Pure-Function Core Libraries, Tested

The shared Python in `lib/` (`song.py`, `tunings.py`, `sloppak.py`,
`loosefolder.py`, `gp2rs.py`, `gp2midi.py`, `retune.py`, etc.) is written
as flat-importable, side-effect-light modules — no `__init__.py`
package, no implicit IO at import time, no global mutable state beyond
the explicit `MetadataDB` and config singletons in `server.py`. The
pytest suite under `tests/` covers pure-function helpers (note/tempo/
tick math, tuning lookups, song wire format) and runs in CI on every
push and PR to `main` against Python 3.12.

**Non-negotiable rules**

- New `lib/` modules MUST be importable with `from <module> import X`
  (flat imports, `pyproject.toml` sets `pythonpath = [".", "lib"]`).
- Pure helpers added to `lib/` SHOULD ship with pytest coverage in
  `tests/test_<module>.py`. Network/filesystem-heavy code is exempt
  but should be split so the pure parts are testable.
- CI MUST stay green on `main`. A failing test on `main` is a P0.

### VI. Observability Over Chattiness

All backend output goes through the stdlib `logging` pipeline configured
by `lib/logging_setup.py`, controlled by `LOG_LEVEL` / `LOG_FORMAT` /
`LOG_FILE`. Plugins receive a pre-configured `context["log"]` namespaced
to `feedBack.plugin.<id>` and MUST use it instead of `print`. HTTP
responses carry a `X-Request-ID` header from `CorrelationIdMiddleware`
and the same id appears as `request_id` in JSON log lines. The
"Settings → Export Diagnostics" bundle (`lib/diagnostics_bundle.py`)
collects logs, hardware, plugin inventory, browser console, and per-
plugin contributed diagnostics into a single redacted zip.

**Non-negotiable rules**

- New backend code MUST use `logging.getLogger(...)` (or the plugin
  `context["log"]`). `print()` and `traceback.print_exc()` are legacy
  and being migrated; do not add new ones.
- Diagnostic redaction is on by default. Anything that ships in the
  bundle (DLC paths, song filenames, IPs, bearer tokens) MUST be
  redacted via `lib/diagnostics_redact.py` rules before export.
- Plugins that contribute diagnostics MUST embed a versioned
  `schema` field (e.g. `"my_plugin.diag.v1"`) and keep payloads
  under 100 KB. Diagnostics is not a backup channel — that is
  `settings.server_files`.

### VII. Versioned, Migration-Aware Settings

User configuration lives in two places: server-side under `CONFIG_DIR`
(SQLite `meta.db`, `config.yaml`, plugin opted-in files) and client-
side in browser `localStorage`. Both can be exported and re-imported
as a single bundle (`POST /api/settings/import`,
`GET /api/settings/export`, feedBack#113). Import is two-phase:
phase-1 validates the entire bundle (schema, paths, encoding) and
phase-2 commits each file atomically via temp+rename. Plugins opt
their server-side files into the bundle via
`settings.server_files` in `plugin.json` (relpaths under `CONFIG_DIR`,
no `..`, no absolute paths).

**Non-negotiable rules**

- Server-side settings imports MUST be all-or-nothing on safety-critical
  failures (path traversal, schema mismatch, decode failure). Plugin
  state mismatches between export and import are recoverable warnings,
  not hard failures.
- Plugins are responsible for their own internal data migration.
  Importing a bundle whose schema predates the running plugin's code
  MUST restore bytes verbatim — the plugin copes at next load.
- The `VERSION` file is the single source of truth for the running
  release; it is auto-bumped from `feedBack-desktop` releases via
  `.github/workflows/sync-version.yml`. Manual edits are reserved for
  out-of-band recovery only.

## Operating Constraints

- **Concurrency model**: FastAPI + uvicorn, sync handlers for the bulk
  of routes, WebSockets for the highway data stream
  (`/ws/highway/{filename}`) and retune progress (`/ws/retune`).
  `MetadataDB` uses a `threading.Lock`; long-running work (rescan,
  retune, sloppak assembly) is dispatched via background threads or
  separate processes, never inline on the request path.
- **Data flow**:
  `library folder → scan (sloppak.py / loosefolder.py) → MetadataDB (SQLite) →
   /api/library*  → static/app.js → /ws/highway → static/highway.js`.
  Sloppak arrangements are served from `arrangements/<id>.json`.
- **Frontend layout invariants**: `#player` is `display:flex;
  flex-direction:column; position:fixed; inset:0`; `#highway` is
  `flex:1`; `#player-controls` sits at the bottom. Hiding the highway
  collapses the layout — use `margin-top: auto` on controls if you
  need to hide it.
- **Plugin load order**: alphabetical by directory name. The
  `playSong` wrapper chain runs outermost-first (last-loaded wrapper
  runs first). Plugins MUST tolerate dependent globals being absent
  at load time and check at runtime
  (`typeof window.X === 'function'`).
- **Module load contract**: a `scriptType:"module"` plugin is injected
  as `<script type="module">`, whose load event fires only after its
  whole static-import graph fetches and evaluates — so the loader's
  completion-by-`onload` guarantee (and the `playSong` wrapper-chain
  order above) is preserved exactly. The host loads `screen.js` once per
  version and `showScreen` re-injects nothing, so a plugin's per-visit
  re-initialization comes from its `screen:changed` handler, not from
  screen.js re-running; ES-module plugins inherit this unchanged (module
  top-level code does not re-execute on same-version re-mount).

## Development Workflow

- **Branching**: never push directly to `main`. Always feature branch
  + PR. Exception: the automated `VERSION` bump from
  `feedBack-desktop`'s release job, which commits to `main` as
  `github-actions[bot]`.
- **Reviews**: PRs run the local Codex review loop
  (`feedback_codex_preflight.md`) and the GitHub Copilot review pass
  (`feedback_copilot_review.md`) before being eligible to merge.
  After pushing a fix, the CodeRabbit loop
  (`feedback_coderabbit_review.md`) runs to silence.
- **Testing**: `pytest` for backend (`requirements-test.txt`),
  Playwright for browser interactions (`tests/browser/`), CI runs both
  on every push/PR to `main`.
- **CHANGELOG**: every PR updates `[Unreleased]`. Releases rename
  `[Unreleased]` to `[X.Y.Z] - YYYY-MM-DD` (the VERSION bump itself is
  automated).
- **Plugin gitlinks**: plugins under `plugins/` are typically separate
  git repos. Branch switches on the main repo can clobber plugin
  directories. Use `git update-index --assume-unchanged` and avoid
  `git clean -fd` near `plugins/`.

## Governance

- This constitution governs the core repo (`server.py`, `lib/`,
  `static/`, `tests/`, `.github/`, `Dockerfile`, `docker-compose.yml`).
- Plugins inherit these principles by default. A plugin MAY add
  stricter rules in its own `CLAUDE.md` / `README.md`, but MUST NOT
  weaken a core principle. A plugin requesting a relaxation (e.g.
  shipping its own SQLite DB outside `CONFIG_DIR`) requires an
  explicit constitutional amendment in this file.
- Amendments require: (a) a PR that updates this file alongside the
  code change, (b) an entry in `CHANGELOG.md` under "Migration notes"
  if user-visible, and (c) a corresponding update to `CLAUDE.md` so
  AI agents and humans see the same source of truth.
- The principles are listed in priority order. When two principles
  conflict (e.g. "vanilla frontend" vs. a plugin that wants to ship
  React), the lower-numbered principle wins by default; the
  higher-numbered principle's escape hatch is to live in a plugin
  with its own bundled assets.

**Version**: 1.3.0 | **Ratified**: 2026-05-09 | **Last Amended**: 2026-07-11