android-reverse-engineering-mcp AGENTS.md

Repository Rules for Coding Agents

Read these before changing code:

1. docs/PROJECT_DIRECTION.md — canonical architecture/product direction.
2. docs/ARCHITECTURE_EVOLUTION_RULES.md — mandatory no-throwaway architecture and long-term evolution gate.
3. docs/CAPABILITY_SPI.md — Capability API, Worker ABI, sandbox and evidence contracts.
4. docs/DEVELOPMENT.md — mandatory development/review/CI rules.
5. docs/ROADMAP.md — release train, milestone scope and acceptance criteria.
6. docs/ROADMAP_0_4_EXECUTION.md — mandatory staged execution plan for milestone 0.4.
7. docs/CODE_OWNERSHIP.md — durable ownership scopes, evidence precedence and SDK-boundary semantics for program-understanding work.
8. docs/PROGRAM_MODEL.md — canonical Program Snapshot, semantic entity/relationship IDs, provider normalization, continuation and query-layer contract for Stage C and later stages.

Mandatory invariants:

• Keep exactly one public safe-android-reverser MCP control plane.
• Do not create framework-specific public MCP servers.
• Only the host Runtime Driver may invoke Docker/Podman; never mount runtime sockets into workers.
• Keep static/framework/native-static workers offline (network=none) and locked down.
• Dynamic privileges require dynamic-opt-in + activation=opt-in; do not weaken static workers.
• Dispatch public operations through manifest ownership and adapters; do not add operation-name/framework switches to the control plane.
• Reuse shared runtime/path/job/evidence infrastructure; do not duplicate it in capability modules.
• Keep framework-specific semantics in framework capabilities. static-core owns generic Android/DEX/JVM/resource triage and routing preflight, not deep semantics for every framework.
• Prefer semantic bounded operations over raw analyzer consoles or generic shell/exec surfaces.
• Preserve provenance and observed / derived / hypothesized evidence states. Never invent numeric confidence.
• CALLS/XREFS are not proven data flow.
• Bound traversal, archive entries, bytes, CPU/time, memory/storage, process output, filesystem scans, and returned results.
• Verify worker/runtime images by required OCI labels and execute immutable image IDs.
• CI should validate invariants and required baseline capabilities, not hard-code the forever-complete capability set.
• Do not merge temporary production architecture. Every accepted mechanism must be expected to survive as a valid abstraction through the intended 1.0 architecture and be extensible without planned replacement.
• Feature coverage may be incomplete; architectural direction may not knowingly be temporary.
• Analyzer, provider, registry, CI, or storage implementation details must not leak into durable public semantic contracts.
• Do not add temporary fallback/compatibility paths merely to preserve a product model that project direction has rejected.
• Code ownership must remain one shared semantic classifier; do not add vendor-specific skip logic or a second SDK-filtering path in later stages.
• The Canonical Program Model must remain one shared semantic vocabulary above private indexes. Do not create framework-specific competing graph models, raw public SQL/graph consoles, or public contracts based on private DEX/Flutter schemas.
• Program Snapshot identity is the SHA-256 of the exact artifact a provider analyzed. Derived child artifacts must not be silently treated as the same snapshot as a parent APK/XAPK; cross-artifact composition requires explicit lineage/correlation evidence.
• Provider pagination must use canonical continuation semantics and report hard-budget truncation explicitly; never paginate by repeatedly slicing a fixed private-index prefix.

Before implementing any non-trivial stage, perform the pre-implementation review in docs/ARCHITECTURE_EVOLUTION_RULES.md. If the design is already known to require replacement in a later milestone, stop and redesign before writing production code.

For milestone 0.4, follow docs/ROADMAP_0_4_EXECUTION.md exactly: implement one stage at a time, complete its test/review/exact-head gate, produce the Gate Report, and stop before beginning the next stage.