flightrules: Instructions file for Claude Code

FlightRules — operating contract

This file is the working contract for anyone (human or agent) changing this repository. It is derived from docs/PRD.md, which remains authoritative. Where this file and the PRD disagree, the PRD wins and this file is wrong and must be fixed.

design.md at the repository root is authoritative only for colours, typography, spacing, layout styling, borders, shadows, icon treatment, logos, illustrations, assets, visual motion and responsive visual rules. It must never change product wording, routes, features, states or information architecture.

What this product is

FlightRules turns SigNoz traces into deterministic release contracts that catch skipped checks, duplicate side effects, unknown tool paths and behavioural drift before an agent canary reaches production.

The graph diff is the product hero. A chatbot is not the interface.

Non-negotiable rules

1. One numbered phase at a time. Do not start a phase whose entry criteria are unmet.
2. A phase is complete only when its tests and its runtime validation have both passed.
3. Code existing is not evidence a feature works. Runtime evidence is required.
4. Never infer an undocumented request or response shape.
5. Never invent a SigNoz endpoint, MCP tool, OpenTelemetry attribute, Foundry field, package option, environment variable or CLI flag.
6. Verify against installed runtime first, then official versioned docs, then the official repository at the pinned commit. A blog post, tutorial, forum answer or recalled syntax is never the sole basis for an implementation decision.
7. Record every external technical decision in docs/research/source-lock.md.
8. When documentation and runtime behaviour disagree, the runtime wins for the installed version, and the mismatch is recorded.
9. Never silently downgrade a requirement.
10. Never replace a required integration with a mock and call the phase complete. Mocks are for unit tests and deterministic offline fixtures only.
11. No placeholder return true, fabricated telemetry, hard-coded dashboard screenshot, invented trace ID, fake MCP response, or manually inserted database row may be used as proof.
12. No unresolved P0 TODO, FIXME, stub, disabled test, skipped test or commented-out implementation may remain at submission.
13. Every MCP write is followed by a read-back that confirms the resource and validates the fields that matter. A successful call is not proof the resource is correct.
14. Every generated dashboard panel must return real data after the seeded demo runs.
15. Every alert must be driven through a real firing state, and a recovery state where the installed SigNoz version supports it.
16. Every trace rule must be tested against both a passing and a violating trace.
17. main stays green. Do not merge a phase branch with failing checks.
18. Focused conventional commits. No co-author trailers.
19. Do not rewrite unrelated code while completing a phase.
20. No secret in source, logs, test snapshots, screenshots, browser storage or telemetry.
21. Never capture chain-of-thought. FlightRules evaluates observable execution structure and safe metadata only.
22. Read the surrounding code and its tests before changing an existing file.
23. After every phase, update the acceptance matrix, evidence log, ADRs and changelog.