qm: Instructions file for Codex

qm

Read docs/SPEC.md first. It is the short source of truth for QM's north stars, subsystems and past mistakes. Where another doc disagrees, the spec wins.

To run and test, see README.md.

Working on the code

Two habits that keep task-focused changes from scarring the rest of the repo:

• Do not add AI authorship attribution to commits or pull requests. Omit Co-authored-by trailers for Codex, Claude, or other AI tools, and omit tool-generated attribution footers such as Generated with Codex. Preserve legitimate human coauthors. CI rejects AI coauthor trailers on new PR commits; do not rewrite existing repository history to remove attribution.
• Fix every instance, not just the reported one. When you find a bug or a pattern worth changing, grep the whole repo (src/, plugins/, test/, scripts/) for the same pattern and fix all of it in the same change. One autocorrected call site with five untouched siblings is a regression waiting to be rediscovered.
• Fixes should make the system simpler, not more complex. Prefer removing or consolidating code over adding a new layer, flag, or special case. If a fix grows the system's surface area, look for the version that shrinks it.
• Never leave comments in the repo. The standard is zero comments: no explanatory comments or docblocks, TODO/FIXME notes, lint/type suppression directives, or commented-out code. Express intent through names, structure, and tests; put rationale in commit messages or PR descriptions. Interpreter shebangs are executable directives, not comments.
• Solve at the layer all paths flow through. Before patching a call site, ask whether the fix belongs in the shared helper, the store interface, or the base module instead. Check for an existing helper before writing a new one-liner. The helper homes: src/util/errors.ts (errMessage/swallow), src/util/async.ts (sleep, createKeyedQueue), src/util/sweeper.ts (periodic loops), src/sandbox/process-poll.ts (process polling/liveness), src/memory/notebook.ts (memory line grammar). Plugins are separate packages and keep their own local copies rather than importing core code — the one exception is the shared plugins/chassis package (the sanctioned home for the plugin↔core plumbing: source-auth signer, signed core-client, node:http helpers, error helpers, CORE_* env), imported by relative path and never importing core. The bar cuts both ways: don't manufacture an abstraction for a pattern with one caller.
• Land PRs through the merge queue. When a PR's checks and reviews pass, gh pr merge <number> queues it rather than merging it. The queue runs CI on the exact commit that will land, reusing the PR's run when main has not moved, and main's own CI then reuses the queue's run. Never bypass the queue with --admin.
• Run independent Wall of shame reviews in parallel for every PR. First triage with one fast, cheap model, the latest Haiku: give it the diff and every lens in the current Wall of shame, and have it mark each lens relevant or not, keeping any lens it is unsure about. Lenses marked always reviewed in the spec skip triage and always get a reviewer. Then dispatch a separate fresh-context subagent or independent reviewer for each relevant lens. Only Honorable mentions may share one combined reviewer. Launch reviews asynchronously and in parallel within available capacity, queuing any overflow. Do not wait for reviews before opening or updating the PR, running checks, or continuing other work. Each reviewer reads their lens and examples, examines the diff and affected paths, and returns accept or request changes, a score out of 100 (higher is better), and 1–2 sentences explaining their assessment. Cite concrete findings and state the smallest correction needed; explain when a lens has no applicable concerns. Scores are informational, with no aggregate score or numeric merge threshold. Put each reviewer's actual verdict, score, and concise assessment in the PR description, labeled by lens and reviewer and tied to the reviewed commit. Update the description as reviews arrive; mark pending reviews honestly and never invent results or substitute the author's self-review. After edits, have independent reviewers reassess affected lenses and explicitly carry forward unaffected results. These reviews run alongside PR work; before merging, every relevant lens must have accepted and all requested changes must be resolved. The Wall of shame review CI check fails until the description's report covers every lens for the PR head: relevant lenses with an Accept verdict, and the rest as Not relevant with the triage model as reviewer and its one-line reason as the assessment.
• Disclose configuration changes in the PR description. Name added, removed, or changed settings, flags, modes, and providers, including defaults, precedence, and supported combinations. Explain why; keep this proportional to the change.
• Keep humans in the loop on schema and data types. Humans must see and review changes to tables and persisted/API payload shapes. Surface them in chat and the PR description as you make them: complete affected old and new shapes, including keys, indexes, constraints, enum variants, and JSON fields, with representative before/after rows. Label invented examples. Account for every field kept, moved, transformed, or dropped; explain migration, backfill, rollout, and compatibility effects. Distinguish approved design, implemented code, and live schema. A migration diff alone is not enough. If configuration or schema is unchanged, say so explicitly.
• Verify locally with the affected tests, not the whole suite. Run the tests covering what you changed plus typecheck and lint, then push and let CI be the full gate — CI shards the suite across parallel runners, and reproducing that serially costs several times the wall clock for the same signal. Judge "affected" by callers rather than by diff size — a one-line edit to a helper with fifty importers reaches all fifty; run everything locally when you can't tell what a change reaches.
• Test what a user or caller sees, never the source. Run the code and assert on its output; don't assert on source text, CSS, or prompt wording. A bug fix's test must fail on the old code through the real path and assert the correct behavior, not the inverse of the specific fix. Don't write checks that can't fail — a fixture compared against itself, a job that always reports success. When a feature is removed, delete its tests.
• Verify non-trivial behavior changes in a live dev instance before opening a PR. When a change is substantial enough that unit tests alone won't prove it works end-to-end — new or changed agent behavior, or anything touching the Slack/web surfaces, orchestrator, directory, or cron flows — boot this worktree with the /dev-instance skill and exercise it through a browser against the configured Slack development workspace before opening a PR. Do this Slack QA in Firefox, never the Slack Mac app, and don't ask permission first — do it on your own; don't wait to be asked. Skip it for trivial refactors, docs, config, or pure-logic changes already covered by tests. Leave review instances running until the PR merges, unless the user asks to stop earlier. After merge, tear down that worktree's instance and verify its processes and lease are gone before removing the worktree. Preserve shared Postgres and persistent data. If the user asks to keep an instance beyond merge, keep its worktree too.
• Keep screenshots out of Git and app assets. Never commit screenshots or create a tracked screenshots directory, including under docs or QA. Capture review images in a temporary directory outside the checkout or an ignored local output directory, and attach them to the PR or host them externally. Do not bundle review screenshots into the app. Only actual product assets, such as icons and instructional media, belong in the app bundle.
• Demo every front-end change in the PR. Anything an operator or user sees rendered — admin/web/portal UI, Slack surfaces, emails — ships with a way for a reviewer to see the result without booting it. Prefer a link to a live demo app (e.g. the built UI served against a small mock API, published internally) so the reviewer can click around the real thing; note in the PR what's mocked. Fall back to screenshots only when a live demo isn't practical (e.g. Slack surfaces, emails), and then show the after state (before/after for changes to something that existed), rendered against realistic data. Attach or externally host these screenshots; never commit them to satisfy this requirement.