Edit content/en/development.md on GitHub ↗

Development

This page is the acceptance contract for a FlyBot change. Hard DSH rules live in AGENTS.md and CONTRIBUTING.md; dated lessons live in LESSONS.md and are promoted here after at least three days.

Verifier honesty

When you report status on a change:

  1. Tip SHA — name the exact commit (git rev-parse HEAD).
  2. Ran — list each command you personally ran at that tip, with pass/fail.
  3. Not run — list material checks you did not run (smoke, Desktop, real-model). Missing evidence is a gap, not a PASS.
  4. No borrowed credit — the author's claims and stale CI on another SHA are not your result.
  5. PASS wording — say only what the evidence supports, for example "unit + lint green at abc1234; smoke not run".

Fail without change

Fix the class, not the sample

If review finds one escape path, fix the shared helper and cover the sibling markers (untrusted-message, untrusted-file, trusted headers). Same-class findings tighten this page or LESSONS.md; do not paper over them with a special case.

List sync

A change that keeps a membership, roster or presence list in sync handles four traps explicitly:

Silent catches and fences

The loop

issue → claim → branch/worktree → red test → fix → gates → PR
      → review at the tip → risk tier → merge queue → release
  1. Issue. Start from a reproducible defect or a concrete maintenance need. Search open and closed issues first. Include expected/actual behaviour, a minimal reproduction, file:line and the environment.
  2. Claim. Skip an issue with a human assignee or a live claim. Assign the maintainer account, add agent-working, comment the branch and a one-line plan.
  3. Branch and red test. Branch from the latest main; one issue, one branch, one PR. Test the class.
  4. Gates. At the exact tip you will link, run in core/:
npm ci
npm run harness          # once: DSH packages for tests
npm run build
npm test
npm run lint
npm run arch-docs

A client change also runs node scripts/build-client.mjs --check; a host change runs the smoke bench. A user-visible change needs a changelog fragment.

Merge rules