Code Review

Review the diff or specified files against these principles.

1. Names must reflect current reality

• Variable and function names should describe what they ARE, not what they used to be.
• If the underlying mechanism changed (e.g. FUSE → NFS), all related names must update.
• Ask: would a new reader be confused by this name?

2. No stale references

• After refactoring, grep for references to the old approach, dead detection logic, abandoned feature flags, comments mentioning removed code.
• If something was tried and reverted, remove ALL traces. The codebase should look like the current approach was always the plan.

3. Simplify detection and guard logic

• A gate like "can this feature run" should check the ONE thing that actually matters.
• Don't chain fallback detections (binary exists OR source exists OR toolchain exists) when one check covers it.

4. Comments document WHY, not WHAT HAPPENED

• Keep: non-obvious technical discoveries, platform quirks, "if you remove this, X breaks because Y."
  • Good: // com.apple.provenance causes SIGKILL when spawned as child process
  • Good: // umount while server is alive panics the macOS NFS client
  • Good: // NFS client uses cookie verifier to decide if cached readdir is valid
• Remove: narrative of what was tried, what was abandoned, what was renamed.
  • Bad: // We changed this from cp to cat to work around the provenance issue
  • Bad: // Wrapper added because FUSE-T was zero-padding (see commit abc123)
  • Bad: // Previously this was called fuseAvailable but we renamed it
• Remove: comments that just restate what the code does without adding reasoning.
• Often no comment is needed at all.

5. Separate install-time from runtime