Syphon_Filter_3/AGENTS.md

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.