Sprint 0: Scaffolding, References, Harness

Prerequisites

None — this is where afs-ld begins. Assumes armfortas and afs-as already exist and compile.

Current state to remediate

The afs-ld/ directory currently sits inside armfortas's working tree as a plain subdirectory. afs-ld/.gitignore was accidentally committed to armfortas history (commit 85d5ba8 "init"), tracking a file that will shortly belong to a separate repo. Before anything else in this sprint, afs-ld must be extracted into its own repo and wired back in as a Git submodule. The tracked .gitignore must be removed from armfortas's index (history can stay; removing a single file at HEAD is clean) so that afs-ld's contents live in the submodule and nowhere else.

Goals

Extract afs-ld into its own repo, wire it back as a submodule, stand up the crate (CLAUDE.md, README, Cargo.toml, skeleton source), clone reference linkers, build the differential harness. End state: cargo test -p afs-ld runs from the parent workspace, at least one test passes meaningfully, and git submodule status lists afs-ld alongside afs-as.

Deliverables

1. Submodule remediation (do first)

Goal: move from "afs-ld is a tracked subdirectory of armfortas" to "afs-ld is a submodule pointing at git@github.com:FortranGoingOnForty/afs-ld.git". Exact sequence:

1. Preserve the current afs-ld contents: copy armfortas/afs-ld/ to a temp location (the .docs/overview.md and sprint files produced in planning are the primary content to preserve; .fackr/ is scratch and can be dropped).
2. Untrack from armfortas: git rm --cached afs-ld/.gitignore && git commit -m "remove accidentally-tracked afs-ld/.gitignore". Confirm git ls-files afs-ld returns empty.
3. Delete the directory from armfortas's working tree (submodule-add will recreate it): rm -rf afs-ld/.
4. Create the external repo FortranGoingOnForty/afs-ld on GitHub (empty, no README — submodule-add will seed it).
5. Initialize locally and push: in a scratch directory,

   git init afs-ld
   cd afs-ld
   <copy preserved contents back>
   git add -A
   git commit -m "init"
   git remote add origin git@github.com:FortranGoingOnForty/afs-ld.git
   git push -u origin trunk
   

6. Add as submodule in armfortas:

   cd <armfortas root>
   git submodule add git@github.com:FortranGoingOnForty/afs-ld.git afs-ld
   git commit -m "add afs-ld submodule"
   

   Confirm .gitmodules gained the stanza:

   [submodule "afs-ld"]
       path = afs-ld
       url = git@github.com:FortranGoingOnForty/afs-ld.git
   

7. Verify with git submodule status — afs-as and afs-ld both listed, each pinned to a commit hash.

Note: the old git rm --cached commit stays in armfortas history. Rewriting history to erase it is more destructive than it's worth for a single .gitignore file. The file at HEAD is gone; that is sufficient.

2. Crate wiring

• Root Cargo.toml adds "afs-ld" to [workspace] members alongside afs-as.
• afs-ld/Cargo.toml: binary + library, zero external dependencies, edition = "2021". Mirror afs-as/Cargo.toml — same keywords, categories, license = "GPL-3.0-only", adjusted description and repository.
• afs-ld/src/lib.rs: public re-exports of Linker, LinkOptions, OutputKind (types are stubs this sprint).
• afs-ld/src/main.rs: CLI that prints usage and exits 0 when run with no args; forwards real args to Linker::run (which errors with "not yet implemented" this sprint).

3. CLAUDE.md and README.md

• afs-ld/CLAUDE.md: mirror afs-as/CLAUDE.md, replacing assembler-isms with linker-isms. Non-negotiable rules: Rust std only, exhaustive matching, caret diagnostics, per-chunk commits, no co-authors, no sprint-number references in commits.
• afs-ld/README.md: one-page intro, supported CLI subset at current state (nothing yet — say so), build/test commands.
• afs-ld/.gitignore: target/, .fackr/, no .docs/ since those files live in the repo. This one is intentionally tracked because it lives inside afs-ld's own repo now, not armfortas's.

4. Reference clones

Add to parent .refs/ (gitignored):

• .refs/ld64/ — git clone --depth 1 https://github.com/apple-oss-distributions/ld64.git. Apple's last publicly released ld64. Authoritative for Apple-parity edge cases.
• .refs/mold/ — git clone --depth 1 https://github.com/rui314/mold.git. Performance reference and a second Rust-adjacent angle on Mach-O.

.refs/llvm/lld/MachO/ already exists from armfortas Sprint 0 — primary architectural reference.

5. Differential harness

afs-ld/tests/common/harness.rs:

pub struct LinkCase {
    pub name: &'static str,
    pub inputs: Vec<PathBuf>,       // .o / .a / .tbd
    pub args: Vec<String>,          // -o, -e, -syslibroot, -l, ...
}

pub struct LinkOutputs {
    pub ours: Vec<u8>,              // afs-ld output
    pub theirs: Vec<u8>,            // system ld output
}

pub fn link_both(case: &LinkCase) -> LinkOutputs;
pub fn diff_macho(ours: &[u8], theirs: &[u8]) -> DiffReport;

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.

6. Skeleton CLI and first failing test

• afs-ld/src/args.rs: hand-rolled argv parser stub that recognizes -o, -e, -arch, and positional inputs. Unknown flags error loudly with a hint.
• afs-ld/tests/reader_empty.rs: attempts to link 0 inputs → empty output, expects the diagnostic "afs-ld: error: no input files". Passes today by producing that exact string.
• 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.

Testing Strategy

• cargo build -p afs-ld compiles from a fresh clone of the parent with git submodule update --init --recursive.
• cargo test -p afs-ld runs harness-sanity, critical-detection, and empty-input tests.
• cargo clippy -p afs-ld -- -D warnings clean.
• Manual verification of submodule state:
  • git ls-files | grep afs-ld in armfortas prints only the .gitmodules entry (and nothing under afs-ld/).
  • git submodule status shows both afs-as and afs-ld with valid commit hashes.
  • git submodule update --init --recursive on a fresh armfortas clone populates afs-ld correctly.

Definition of Done

• The accidentally-tracked afs-ld/.gitignore is removed from armfortas's index at HEAD.
• afs-ld exists as a standalone GitHub repo under FortranGoingOnForty.
• afs-ld is wired into armfortas as a Git submodule, visible in .gitmodules and git submodule status.
• armfortas/Cargo.toml lists afs-ld in [workspace] members.
• afs-ld/CLAUDE.md, README.md, Cargo.toml, src/lib.rs, src/main.rs, src/args.rs all committed in the new repo.
• .refs/ld64/ and .refs/mold/ cloned.
• Differential harness substrate runs, correctly reports zero diffs on identical byte slices, correctly reports critical diffs on intentionally-different byte slices.
• cargo test --workspace green.