# AGENTS.md — Syphon Filter 3 Decompilation

Matching decompilation of **Syphon Filter 3 (USA)** for PlayStation. The goal is to rebuild original game binaries from C source with byte-for-byte identical output. A native PC port is out of scope until the matching decompilation is established.

## Session-start load order

At the start of every session, read these files in order:

1. `AGENTS.md` — standing agent rules.
2. `PROJECT_CONTEXT.md` — permanent project constitution.
3. `phase-ends/DIGEST.md` — completed-phase findings.
4. `phase-ends/CURRENT_PHASE.md` — active in-phase state, when present.
5. The active phase plan in `phase-ends/`.
6. Task-relevant records under `docs/`.

The active plan and current-phase record govern day-to-day execution; do not duplicate their evolving state in this file.

## Mandatory behavior

1. **One task at a time.** Present and complete one task before beginning the next. A task that writes code, changes a design, or modifies project state is its own task.
2. **Explain before changing code or design.** State the approach, significant choices, and verification method before writing non-trivial code or changing architecture.
3. **Never overwrite blind.** Read an existing file before changing it. State what changes and why. Preserve comments and document headers.
4. **Evidence first.** Ghidra is the static oracle and PCSX-Redux is the runtime oracle. Do not present assumptions about game behavior, addresses, ABI, types, file formats, or compiler behavior as facts.
5. **A match is byte-for-byte.** A function is matched only if its compiled code is instruction-identical to the original and the full-binary hash check remains green. Functional equivalence is not a match.
6. **Keep unmatched code as assembly.** Correct-looking C that does not match stays behind an explicit `NON_MATCHING` guard or assembly stub; it must not enter the default matching build.
7. **Verify from clean state.** Report a build or match only after the documented clean rebuild and relevant object/binary comparison pass. Read command exit codes, not merely their final output line.
8. **Check duplicates before matching.** Match a shared body once where possible, then share it through a documented source/registry mechanism.
9. **Document uncertainty.** Label hypotheses and unverified addresses. Record source build/region for every externally sourced address; never treat JP or prototype data as USA evidence without validation.
10. **Stop on unexplained failure.** If two distinct root-cause attempts fail, stop and report the evidence rather than masking the failure or redefining success.

## ROM and repository firewall

- Never commit the disc dump, extracted disc contents, disassembly generated from the game, assets, build outputs, expected binaries, Ghidra database, RAM dumps, proprietary Sony SDK files, or session archives.
- Review `git status` before every commit.
- Never use `git clean -x` or `git clean -fdx`. It can destroy ignored reverse-engineering databases and local dumps. Define a project-specific `make clean` later for regenerable build output only.
- Keep generated ROM-derived material in ignored paths such as `disks/`, `extracted/`, `asm/`, `assets/`, `build/`, `expected/`, `ghidra/`, and `dumps/`.
- Do not copy game bytes, disassembly listings, or ROM-derived fixtures into documentation, tests, badges, reports, or public artifacts.

## Environment

- Use the installed Ghidra PSX loader when importing PS-X EXE files. Record the detected PsyQ/SDK evidence rather than assuming a toolchain.
- Use PCSX-Redux for runtime breakpoints, RAM snapshots, and controlled before/after tests when static analysis cannot prove a load address or behavior.
- Before any build pipeline work, verify the repository resides on a native Linux filesystem with reliable file permissions and watching. Do not build on a network/shared mount.
- Keep local tools under `tools/`; record versions, commands, and download provenance in `docs/SETUP.md` once Phase 0 creates it.

## Matching workflow

1. Extract the original binary deterministically and record hashes.
2. Import it with the PSX loader; preserve loader settings and record static findings.
3. Build a splat/disassembly/linker baseline that rebuilds the original binary from assembly before introducing C.
4. Fingerprint the original compiler/assembler/flags using small probe functions; do not copy another project’s settings without byte evidence.
5. For each C candidate: inspect references and duplicates, compile, compare against the original object/function, then run the full binary check.
6. Record reusable compiler/codegen discoveries in a matching cookbook and tooling immediately after a verified match.

## Phase and session discipline

- Every phase begins with a task-by-task plan, verification criteria, and explicit developer approval.
- Keep current in-phase state in `phase-ends/CURRENT_PHASE.md`; write a checkpoint before ending a session.
- After every four completed tasks, re-read these mandatory rules and state: `Rules check — re-read complete. Continuing with [next task].`
- A phase closes only after every checklist item is explicitly verified and the developer confirms the milestone. Then write a PhaseEnd file, update the digest, and stop; do not begin the next phase in the same session.