fortrangoingonforty/afs-ld / c1785ff

+# Sprint 0-9 Closeout Checklist

+

+Concrete closeout checklist based on the current codebase audit.

+

+Current conclusion: we are not ready to honestly declare Sprint 10 complete-in-practice yet.

+The main blockers are:

+

+- Sprint 0's tolerated-diff categories are still deferred until afs-ld can emit real linked output for Mach-O-to-Mach-O differential checks.

+

+## Sprint 10 Gate

+

+Do not declare "we are on Sprint 10" until all of these are true:

+

+- [x] Sprint 9 reloc referents are remapped to atom-aware forms.

+- [x] Sprint 8 resolution orchestration exists as a real callable stage, not just loose helper APIs.

+- [x] `cargo test -p afs-ld` is green after the closeout work.

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings` is green after the closeout work.

+- [x] `README.md` and sprint docs no longer materially misstate the current state of the crate.

+

+## Recommended Order

+

+- [x] Close Sprint 9 reloc-to-atom remap first.

+- [x] Close Sprint 8 resolution orchestration and option coverage second.

+- [x] Close Sprint 6 TBD/SDK search gaps third.

+- [x] Close Sprint 4 nested archive support fourth.

+- [ ] Finish the deferred Sprint 0 differential-harness tolerance work once afs-ld can emit real output.

+

+## Cross-Sprint Exit Criteria

+

+- [ ] Every closeout chunk lands with tests.

+- [ ] Every bug fix or behavioral gap gets a regression test.

+- [ ] No newly-discovered roadmap/code mismatch is left undocumented.

+- [ ] Any user-facing diagnostic we touch stays deterministic and testable.

+

+## Sprint 0

+

+Status: closed

+

+Validated:

+

+- [x] `afs-ld` exists as its own git submodule in the parent workspace.

+- [x] Parent `Cargo.toml` includes `afs-ld` as a workspace member.

+- [x] `CLAUDE.md`, `README.md`, crate wiring, and test harness scaffolding exist.

+- [x] Reference repos are present under parent `.refs/` (`ld64`, `mold`, `lld`).

+- [x] `tests/reader_empty.rs` enforces the empty-invocation CLI contract.

+- [x] `tests/diff_harness_sanity.rs` and `tests/diff_harness_finds_critical.rs` exist and pass.

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings` is currently clean.

+

+Remaining closeout work:

+

+- [x] Explicitly downscope Sprint 0 docs so the current diff harness is described as synthetic until end-to-end linking exists.

+- [ ] Add tolerated-diff categories once real Mach-O-to-Mach-O comparisons exist.

+

+## Sprint 1

+

+Status: closed

+

+Validated:

+

+- [x] Mach-O constants are duplicated locally in `src/macho/constants.rs`.

+- [x] `MachHeader64` parsing exists and rejects malformed headers.

+- [x] Load-command dispatch exists and preserves unknown commands as raw bytes.

+- [x] Segment and section-header metadata parsing exists.

+- [x] `LC_BUILD_VERSION` and `LC_LINKER_OPTIMIZATION_HINT` decoding exists.

+- [x] `--dump` exists through `src/dump.rs` and `src/main.rs`.

+- [x] Corpus round-trip tests pass in `tests/reader_corpus_round_trip.rs`.

+

+Remaining closeout work:

+

+- [x] Add an `otool -lV` parity test for dumper output shape across the corpus.

+- [x] Add a panic-focused malformed-input stress pass beyond the current unit tests so the "no panics on malformed input" claim is defensible.

+

+## Sprint 2

+

+Status: closed

+

+Validated:

+

+- [x] Section classification exists in `src/section.rs`.

+- [x] `InputSection` carries section data and raw relocation bytes.

+- [x] `RawNlist` / `InputSymbol` parsing and classification exist in `src/symbol.rs`.

+- [x] Common symbols, weak flags, private externs, and indirect aliases are surfaced.

+- [x] `StringTable` exists and handles suffix-dedup overlaps.

+- [x] `DysymtabCmd` is parsed and exposed through `ObjectFile`.

+- [x] `ObjectFile` integrates header, commands, sections, symbols, strings, and dysymtab.

+

+Remaining closeout work:

+

+- [x] Add `nm -a` parity tests for symbol view and classification.

+- [x] Add `otool -r` parity checks for relocation-offset surfaces promised by Sprint 2, with section/load-command parity covered by the Sprint 1 `otool -lV` gate.

+- [x] Add stronger malformed-symbol / malformed-string-table stress coverage if we want the "never panics" bar to be explicit.

+

+## Sprint 3

+

+Status: closed enough for current closeout

+

+Validated:

+

+- [x] ARM64 relocation constants exist.

+- [x] Raw relocation parsing and writing exist.

+- [x] Fused `Reloc` form exists.

+- [x] `ADDEND` and `SUBTRACTOR + UNSIGNED` pairing is fused in `parse_relocs`.

+- [x] Validation logic exists in `validate_relocs`.

+- [x] Write-side round-trip support exists.

+- [x] Unit coverage is broad and current corpus relocation round-trips pass.

+

+Remaining closeout work:

+

+- [x] No audit-blocking work found for Sprint 3.

+

+## Sprint 4

+

+Status: closed

+

+Validated:

+

+- [x] BSD, SysV, and GNU-thin archive flavors are recognized.

+- [x] Archive headers and name decoding are implemented.

+- [x] Symbol-index parsing exists for BSD and SysV archives.

+- [x] Lazy member fetch exists via `fetch_object_defining`.

+- [x] `libarmfortas_rt.a` is exercised by `tests/archive_runtime.rs`.

+- [x] Archive dump mode exists via `--dump-archive`.

+

+Remaining closeout work:

+

+- [x] Implement one-level nested archive support (`.a` member inside `.a`) and preserve provenance for diagnostics.

+- [x] Formally treat `resolve::force_load_archive` / `force_load_all` as the Sprint 4 completion surface and document that surface instead of adding a parallel archive-only helper.

+- [x] Add `ar -t` shape/parity coverage for `--dump-archive`.

+

+## Sprint 5

+

+Status: partially closed

+

+Validated:

+

+- [x] `DylibFile` exists and parses binary `MH_DYLIB`.

+- [x] `LC_ID_DYLIB`, dependency dylib commands, ordinals, and rpaths are decoded.

+- [x] Export trie decoding exists with cycle/depth protection.

+- [x] Real clang-built dylib coverage exists in `tests/dylib_integration.rs`.

+- [x] Dylib dump mode exists via `--dump-dylib`.

+

+Remaining closeout work:

+

+- [ ] Prove recursive re-export / umbrella lookup behavior with a focused test, not just dependency collection.

+- [ ] Confirm the public dylib surface matches what Sprint 5 intended for re-exported symbols, not only direct exports.

+

+## Sprint 6

+

+Status: closed

+

+Validated:

+

+- [x] The custom YAML subset parser exists in `src/macho/tbd_yaml.rs`.

+- [x] TBD schema decoding exists in `src/macho/tbd.rs`.

+- [x] `DylibFile::from_tbd` exists and materializes TBDs into the same linker-facing surface.

+- [x] Real `libSystem.tbd` smoke/integration coverage exists in `tests/tbd_smoke.rs` and `tests/tbd_integration.rs`.

+- [x] TBD dump mode exists via `--dump-tbd`.

+

+Remaining closeout work:

+

+- [x] Implement SDK `-syslibroot` library search helpers for `.tbd` / `.dylib`.

+- [x] Implement framework search helpers promised by Sprint 6.

+- [x] Make target filtering fail loudly when the requested target is not exported, instead of only materializing matching targets when the caller already knows one exists.

+- [x] No further audit-blocking work found for Sprint 6 in the current helper/test surface.

+

+## Sprint 7

+

+Status: closed

+

+Validated:

+

+- [x] `Symbol` sum type exists with the planned major variants.

+- [x] `StringInterner`, opaque ids, and `SymbolTable` exist.

+- [x] The insertion matrix is heavily unit-tested.

+- [x] Weak/strong/common coalescing behavior is covered in unit tests.

+- [x] Alias-cycle detection and chain resolution exist.

+- [x] Transition logging exists.

+

+Remaining closeout work:

+

+- [ ] Add the differential weak-coalescing / duplicate-behavior coverage against system `ld` that Sprint 7 originally called for.

+

+## Sprint 8

+

+Status: closed

+

+Validated:

+

+- [x] Archive seeding, object seeding, and dylib seeding exist.

+- [x] Fixed-point archive fetch draining exists.

+- [x] `force_load_archive` and `force_load_all` helpers exist in `src/resolve.rs`.

+- [x] Undefined classification exists for `Error`, `Warning`, `Suppress`, and `DynamicLookup`.

+- [x] Did-you-mean support exists.

+- [x] Duplicate-symbol and undefined-symbol formatting helpers exist.

+- [x] Real integration coverage exists for archive pull plus unresolved-symbol reporting.

+

+Remaining closeout work:

+

+- [x] Add a real orchestration entrypoint for resolution (`seed -> optional force load -> drain -> classify`) that can be called as a coherent stage.

+- [x] Add option/state plumbing for `all_load`, `force_load`, and undefined treatment so resolution is not just a bag of helper APIs.

+- [x] Add an archive order-sensitivity test.

+- [x] Add dedicated tests for `force_load_archive` and `force_load_all`.

+- [x] Add dedicated tests for `UndefinedTreatment::Warning`, `Suppress`, and `DynamicLookup`.

+- [x] Add a dedicated test that unresolved weak refs stay accepted regardless of treatment.

+- [x] Tighten diagnostics toward the Sprint 8 format by carrying section/offset provenance and aggregate repeated relocation sites when available.

+

+## Sprint 9

+

+Status: closed

+

+Validated:

+

+- [x] Atom model and atom table exist.

+- [x] Section splitting at symbol boundaries exists.

+- [x] `.alt_entry` folding exists.

+- [x] CString atom splitting exists and is integration-tested.

+- [x] Compact-unwind atom splitting and `parent_of` wiring exist.

+- [x] Backpatching of `Symbol::Defined { atom }` exists.

+- [x] `N_NO_DEAD_STRIP` and weak-def flags are propagated into atom flags.

+- [x] Embedded payload addends on symbol-based data relocs are folded into local atom offsets or preserved on external refs.

+

+Remaining closeout work:

+

+- [x] Remap relocations from raw section/symbol referents into atom-aware referents.

+- [x] Add atom-local relocation storage or an equivalent per-atom relocation view.

+- [x] Ensure same-object references point at target atoms, not raw section offsets.

+- [x] Add a focused integration test proving a local branch or data reference resolves to the callee/target atom.

+- [x] Add a boundary-crossing reloc diagnostic test.

+- [x] Confirm no raw section-relative relocation state leaks into Sprint 10 inputs.

+- [x] No further audit-blocking work found for Sprint 9 in the current corpus and targeted local-addend probes.

+

+## Documentation Closeout

+

+- [x] Update `README.md` so it no longer says the crate is only Sprint 0 scaffolding.

+- [x] Refresh sprint docs whose deliverables have been implemented under a different surface than originally planned.

+- [x] Keep `CLAUDE.md` as the authority for discipline, but make user-facing docs match the actual code.

+

+## Verification Commands

+

+- [x] `cargo test -p afs-ld`

+- [x] `cargo clippy -p afs-ld --all-targets -- -D warnings`

+- [ ] Focused xcrun-backed checks when touching reader/resolve/atom/TBD/dylib paths:

+  - [x] `cargo test -p afs-ld --test reader_corpus_round_trip -- --nocapture`

+  - [x] `cargo test -p afs-ld --test resolve_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test atom_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test dylib_integration -- --nocapture`

+  - [x] `cargo test -p afs-ld --test tbd_integration -- --nocapture`

+`DiffReport` categorizes byte differences as `Tolerated` (UUID, timestamp, temp-path hashes) or `Critical` (anything else). Critical diffs fail the test.

+

+Closeout note: the current Sprint 0 surface is intentionally synthetic. `diff_macho` exists and is tested, but `link_both` remains a placeholder until afs-ld can emit real linked output. That means the current harness validates diff categorization logic, not end-to-end linker parity yet.

+- `afs-ld/tests/diff_harness_sanity.rs`: exercises the diff surface against two identical synthetic byte slices and expects zero diffs. Passes.

+- `afs-ld/tests/diff_harness_finds_critical.rs`: feeds the harness two synthetic binaries that differ in a non-tolerated byte range and asserts the harness reports `Critical`. Passes.

+- Differential harness substrate runs, correctly reports zero diffs on identical byte slices, correctly reports critical diffs on intentionally-different byte slices.

+Closeout note: alongside the original unit coverage, `tests/reader_malformed_stress.rs`

+now runs deterministic truncated/header-corruption cases over real corpus-built

+objects to defend the "no panics on malformed input" bar, and

+`tests/reader_tool_parity.rs` checks the `--dump` load-command surface against

+`otool -lV` across the afs-as corpus.

+

+Closeout note: `tests/reader_malformed_stress.rs` now also covers malformed

+symbol/string-table variants derived from real corpus objects so the reader's

+symbol and string surfaces are exercised under targeted bad-input cases, not

+just hand-written unit fixtures. `tests/reader_tool_parity.rs` now also checks

+symbol classification against `nm -a` and raw relocation tables against

+`otool -r` across the afs-as corpus.

+

+Closeout note: the force-load surface landed in the resolver as

+`resolve::force_load_archive` / `resolve::force_load_all`, and one-level

+nested archives are expanded through the fetched-member path with provenance

+chains such as `outer.a(inner.a)(foo.o)`. `--dump-archive` now intentionally

+prints the same member listing shape as `ar -t`, and parity is checked

+against both generated archives and `libarmfortas_rt.a` when available.

+

+Implemented via the resolver-level helpers

+`resolve::force_load_archive` / `resolve::force_load_all`, which pre-fetch

+archive members against the live linker input registry. Sprint 19 wires the

+CLI surface.

+Closeout note: the implemented entrypoint is

+`resolve(inputs, table, opts) -> ResolutionReport`. The current library

+surface applies archive force-loading as archives are encountered in

+command-line order so left-to-right archive behavior stays explicit.

+

+    -> Result<ResolutionReport, ResolutionError>

+    seed_and_resolve_in_link_order(inputs, table, opts);

+    classify_unresolved(table, opts.undefined_treatment);

+- In the implemented surface these happen when the named archive is encountered in link order, which preserves left-to-right linker semantics while still feeding the same resolution/classification pipeline.

+      referenced by program.o(__TEXT,__text + 0x34)

+      referenced by runtime.o(__TEXT,__text + 0x120)

+  defined in: a.o (__TEXT,__text + 0x0)

+  also in:    b.o (__TEXT,__text + 0x0)

+# AFS-LD

+

+Local working guide for agents in `afs-ld`. Keep this file untracked.

+`CLAUDE.md` is the tracked, authoritative policy file; this document adds a

+reality-checked snapshot of the current implementation so we do not confuse the

+roadmap with shipped code.

+

+## Repository Context

+

+`afs-ld` is the standalone ARM64 Mach-O linker for the ARMFORTAS toolchain. It

+sits beside `afs-as` as a submodule in the `armfortas` workspace and is meant

+to replace Apple's `ld` for binaries produced by armfortas.

+

+The project boundary is intentionally clean:

+

+- `afs-as` emits `MH_OBJECT`.

+- `afs-ld` reads `.o`, `.a`, `.dylib`, and `.tbd`.

+- armfortas should eventually hand final linking to `afs-ld` rather than to

+  the system linker.

+

+The project is Mach-O only, macOS only, arm64 only, stdlib only.

+

+## Definition Of Done

+

+The real finish line is not "parses some objects" or "links hello world once."

+It is parity with Apple's `ld` for the binaries armfortas and fortsh need:

+

+- arm64 Mach-O executables and dylibs

+- static archive linking

+- dylib and TBD ingestion

+- dyld metadata that works on real macOS systems

+- ad-hoc signing so output executes on Apple Silicon

+- deterministic output

+- enough correctness to link fortsh without ARM-specific workarounds

+

+## Current Reality

+

+This repo is ahead of Sprint 0 scaffolding, but it is not yet a full linker.

+The roadmap in `.docs/overview.md` and `.docs/sprints/` is broader than the

+code that exists today.

+

+What is implemented now:

+

+- hand-rolled CLI parsing for a small flag subset plus dump modes

+- Mach-O header/load-command/section/symbol/string-table reading

+- relocation parsing, fusion, validation, and round-trip support

+- archive parsing and lazy member fetch support

+- binary dylib parsing and export-trie walking

+- TAPI TBD v4 parsing, including the custom YAML subset parser

+- linker-side symbol interning, symbol table modeling, and resolution passes

+- subsections-via-symbols atomization

+- `--dump`, `--dump-archive`, `--dump-dylib`, and `--dump-tbd`

+

+What is not implemented yet:

+

+- real `Linker::run` output production

+- output layout and Mach-O writing

+- dyld metadata synthesis

+- code signing

+- dead-strip / ICF / thunks

+- real differential linking against Apple `ld`

+- driver integration with armfortas

+- the full `ld`-compatible CLI surface described in Sprint 19

+

+Important practical note:

+

+- `src/lib.rs` still returns `LinkError::NotYetImplemented` for real link runs.

+- `tests/common/harness.rs::link_both` still panics because full end-to-end

+  linker execution has not landed.

+- `README.md` still describes the crate as "Sprint 0 scaffolding only," which is

+  now too pessimistic for the read-side code but still accurate for the actual

+  link-producing path.

+

+As of 2026-04-15 in this checkout, `cargo test -p afs-ld` is green.

+

+## Strengths

+

+- The read-side core is already substantial and well-tested.

+- The project has strong bespoke discipline: no `clap`, `serde`, `object`,

+  `goblin`, `byteorder`, or other format-parsing shortcuts.

+- Raw wire structures are modeled explicitly and usually paired with

+  round-trip-oriented tests.

+- The type modeling is strong: opaque ids, interned strings, explicit symbol

+  states, explicit atom ownership, explicit relocation referents.

+- Real-world fixtures are already in play: afs-as corpus objects,

+  `libarmfortas_rt.a`, `libSystem.tbd`, and small clang-built dylibs.

+- The codebase already separates concerns cleanly enough that writer/layout work

+  can land without tearing up the read-side foundation.

+- Dump modes make inspection easy and are useful while the full writer does not

+  exist yet.

+

+## Weaknesses And Risk Areas

+

+- The actual link-producing pipeline does not exist yet, so the hardest parity

+  bugs are still ahead of us.

+- Some tracked docs are aspirational. `.docs/overview.md` is the intended end

+  state, not a guarantee that every listed module already exists.

+- `README.md` is stale in the opposite direction: it understates how much

+  read-side work has landed.

+- The current diagnostics surface is still minimal. `src/diag.rs` only prints

+  `afs-ld: error: ...`; the richer caret diagnostics are planned, not present.

+- The CLI surface is intentionally tiny right now. Any work that assumes

+  `ld`-compatibility must start by checking `src/args.rs`, not by trusting the

+  sprint plan.

+- Performance characteristics are mostly unknown because the writer, layout, and

+  full-link path are not in place yet.

+- The differential harness is only half-built: the diff engine exists, but the

+  "run both linkers" machinery is not wired.

+- Several future modules named in the roadmap do not exist yet:

+  `layout.rs`, `driver.rs`, `map.rs`, `gc.rs`, `icf.rs`, `synth/`,

+  `macho/writer.rs`, and the code-signing path are all still planned work.

+

+## Build And Test

+

+Primary commands:

+

+```bash

+cargo build -p afs-ld

+cargo test -p afs-ld

+cargo clippy -p afs-ld --all-targets -- -D warnings

+```

+

+Useful targeted commands:

+

+```bash

+cargo test --lib -p afs-ld

+cargo test --test reader_corpus_round_trip -p afs-ld

+cargo test --test archive_runtime -p afs-ld

+cargo test --test dylib_integration -p afs-ld

+cargo test --test tbd_integration -p afs-ld

+cargo test --test resolve_integration -p afs-ld

+cargo test --test atom_integration -p afs-ld

+cargo test -p afs-ld -- <substring>

+```

+

+Environment assumptions:

+

+- macOS on Apple Silicon

+- Xcode command-line tools available through `xcrun`

+- access to the parent workspace, especially `runtime/` and `.refs/`

+

+Integration tests already shell out to system tools in a few places. Do not

+replace those with fake fixtures if a real toolchain interaction is the thing

+being tested.

+

+## Project Structure

+

+Actual source tree today:

+

+```text

+afs-ld/

+├── CLAUDE.md

+├── README.md

+├── .docs/

+│   ├── overview.md

+│   └── sprints/

+├── src/

+│   ├── archive.rs

+│   ├── args.rs

+│   ├── atom.rs

+│   ├── diag.rs

+│   ├── dump.rs

+│   ├── input.rs

+│   ├── leb.rs

+│   ├── lib.rs

+│   ├── main.rs

+│   ├── resolve.rs

+│   ├── section.rs

+│   ├── string_table.rs

+│   ├── symbol.rs

+│   ├── macho/

+│   │   ├── constants.rs

+│   │   ├── dylib.rs

+│   │   ├── exports.rs

+│   │   ├── reader.rs

+│   │   ├── tbd.rs

+│   │   └── tbd_yaml.rs

+│   └── reloc/

+│       └── mod.rs

+└── tests/

+    ├── common/harness.rs

+    ├── archive_runtime.rs

+    ├── atom_integration.rs

+    ├── diff_harness_*.rs

+    ├── dylib_integration.rs

+    ├── reader_*.rs

+    ├── resolve_integration.rs

+    ├── tbd_*.rs

+    └── reader_corpus_round_trip.rs

+```

+

+Planned future modules listed in the docs should be treated as design intent,

+not as present-tense implementation.

+

+## Implemented Pipeline Vs Planned Pipeline

+

+Implemented today:

+

+```text

+argv

+  -> args.rs

+  -> dump/read paths

+  -> archive/object/dylib/TBD ingestion

+  -> symbol/section/reloc decoding

+  -> resolve.rs

+  -> atom.rs

+```

+

+Current real-link path:

+

+```text

+argv -> args.rs -> Linker::run -> NotYetImplemented

+```

+

+Planned end-to-end pipeline from the roadmap:

+

+```text

+args -> inputs -> resolve -> atomize -> layout -> apply relocs

+     -> synth sections -> write -> sign

+```

+

+When you are planning work, always identify which of those stages is real in

+this checkout and which stage is still only described in docs.

+

+## Development Guidance

+

+### 1. Trust code and tests over roadmap prose

+

+Read these in order before substantial work:

+

+1. `CLAUDE.md`

+2. `.docs/overview.md`

+3. the relevant sprint file in `.docs/sprints/`

+4. the actual Rust module you will touch

+5. the tests covering that module

+

+If the docs and the code disagree, treat the code plus tests as the truth about

+what exists today, then decide whether the docs need to be refreshed.

+

+### 2. Keep the bespoke contract intact

+

+- Stdlib only unless a dependency discussion happens first.

+- Do not couple afs-ld to afs-as at a Rust type level.

+- Duplicate Mach-O constants locally when needed.

+- Do not hide format details behind clever abstractions that erase wire truth.

+

+### 3. Preserve the wire

+

+- Keep raw bytes or raw fields accessible when lossless re-emission matters.

+- Prefer explicit parse and write pairs for on-disk structures.

+- Avoid converting fixed-size or padded wire data into lossy higher-level forms

+  unless the raw representation is still available somewhere.

+- If a new decoder lands, pair it with tests that prove it round-trips or at

+  least preserves the exact bytes relevant to the current stage.

+

+### 4. Be explicit about incomplete work

+

+- Hard errors are better than silent wrong answers.

+- If something is not implemented, say so directly.

+- Do not introduce "temporary" behavior that quietly emits malformed Mach-O.

+- Do not soften a missing feature into a no-op unless the flag or structure is

+  explicitly intended to be ignored.

+

+### 5. Exhaustive matches matter

+

+- Prefer enums for wire forms and linker-side states.

+- Avoid catch-all `_` arms in production matches when a new variant should force

+  the compiler to help us.

+- When adding a new variant, update every relevant match deliberately.

+

+### 6. Keep dump surfaces useful

+

+- `--dump*` modes are an active debugging tool, not a side feature.

+- When new reader functionality lands, extend the corresponding dump output.

+- If you add a new parsed field but the dump cannot show it, the repo loses one

+  of its best inspection surfaces.

+

+### 7. Respect deterministic behavior

+

+- Avoid nondeterministic iteration when output order matters.

+- Avoid timestamps, random ids, or unstable hashing in any future write path.

+- When adding diagnostics, keep them stable and testable.

+

+## Testing Practices

+

+- Every bug fix gets a regression test.

+- New parser behavior should land with unit tests close to the module.

+- When touching integration behavior, prefer real fixtures over mocked ones.

+- For archive work, look first at `tests/archive_runtime.rs`.

+- For dylib and TBD work, look first at `tests/dylib_integration.rs`,

+  `tests/tbd_integration.rs`, and `tests/tbd_smoke.rs`.

+- For reader invariants, `tests/reader_corpus_round_trip.rs` is a key guardrail.

+- For resolution and atomization, `tests/resolve_integration.rs` and

+  `tests/atom_integration.rs` should move with the code.

+- If you add future write-side functionality, extend the differential harness

+  rather than building a parallel ad hoc test path.

+

+Run focused tests first, then widen:

+

+- module-local or single integration test while developing

+- `cargo test -p afs-ld` before handing work off

+- `cargo clippy -p afs-ld --all-targets -- -D warnings` when changing code paths

+  broadly enough to justify it

+

+## Documentation Practices

+

+- `CLAUDE.md` is policy and development discipline.

+- `.docs/overview.md` is the intended architecture and scope.

+- `.docs/sprints/` is the staged roadmap.

+- `README.md` is user-facing and currently stale relative to the read-side code.

+

+When a change materially shifts reality, update the tracked docs that are now

+misleading. This is especially important in this repo because the roadmap is

+ambitious and can otherwise create false assumptions for future work.

+

+## References

+

+Use the parent repository's references when you need to confirm Mach-O or linker

+behavior instead of inventing from memory:

+

+- `.refs/llvm/lld/MachO/` for architecture and pass structure

+- `.refs/ld64/` for Apple-parity edge cases

+- `.refs/mold/` for performance ideas and comparative implementation choices

+

+Also use Apple's Mach-O and arm64 relocation headers as the numeric source of

+truth for constants mirrored in `src/macho/constants.rs`.

+

+## Working Style For This Repo

+

+- Prefer small, reviewable changes.

+- Keep commit messages terse and imperative.

+- Do not mention sprint numbers in commit subjects.

+- Avoid monolithic "land the whole linker" changes; the sprint plan is granular

+  for a reason.

+- Before implementing a planned module from the roadmap, make sure the crate

+  actually has the prerequisites the sprint assumed.

+- If you are about to say "the docs say this exists," stop and confirm with

+  `ls`, `rg`, and the tests.

+

+## Practical Shortcuts

+

+- Use `rg --files` and `rg` first; the repo is small enough that this is fast

+  and keeps context grounded in the actual tree.

+- For current status, start with `src/lib.rs`, `src/main.rs`, `src/args.rs`,

+  `tests/common/harness.rs`, and `README.md`.

+- For architectural intent, then read `.docs/overview.md` and the relevant

+  sprint file.

+

+That order will save a lot of confusion.