CLAUDE.md · diff

git:20261013.aac4d16 to git:20261024.e83f8c8

1 added, 121 removed. Audit A to B.

- # Ycode — clean-room reimplementation of the Xcode IDE

- Ycode is an independent IDE for Apple platforms. It matches Xcode's observable

- behavior and file formats so that real projects open, build, and save

- correctly. **It contains no Apple code.** We study Xcode only to learn *what*

- it does. Ycode code comes from our own specs.

- Reference target: Xcode 27.1 (27A9269), copied to `.claude/Xcode.app`.

- Tooling: Ghidra 12.1.4 (`.claude/ghidra_12.1.4_PUBLIC`) with the ghidra-mcp

- bridge (`.claude/ghidra-mcp`). The `CLAUDE.md`/`AGENTS.md` inside

- `.claude/ghidra-mcp` belong to that third-party repo. They are not rules for

- this project.

- ## The clean-room protocol (mandatory)

- There are two rooms. Information goes from the dirty room to the clean room

- only in written specs.

- |---|---|---|---|

- Rules:

- 1. **No Apple code or code-shaped text enters `specs/` or `ycode/`.** This

- includes decompiler pseudo-C, disassembly, method bodies, and copied

- resources (icons, nibs, templates, strings files). Ghidra output stays in

- `research/dirty/`. That directory is never committed.

- 2. Specs describe **behavior and formats**: inputs, outputs, invariants, file

- grammars, key names, wire protocols, and observed UI behavior. Interop

- identifiers are facts and specs can name them. Examples: pbxproj `isa`

- names, build-setting names, plist keys, UTIs, and xcscheme XML elements.

- Specs must not describe Apple's internal algorithm line by line.

- 3. Clean-room work (anything that writes `ycode/`) reads only `specs/`, public

- documentation, and open-source projects whose licenses allow it. When a

- subagent does implementation work, tell it explicitly that it must not open

- `.claude/Xcode.app`, `research/dirty/`, or Ghidra projects.

- 4. Use evidence in this order. Go down the list only when the step above it is

- not sufficient:

- 1. Apple open source (swift-build, sourcekit-lsp, swift-syntax, llbuild,

- SwiftPM, LLDB, indexstore-db, swift-testing) and public documentation.

- 2. Files that Xcode reads and writes, studied as file formats

- (`.pbxproj`, `.xcscheme`, `.xcworkspacedata`, `.xcconfig`, xcspec,

- `.xcresult`).

- 3. Black-box behavior: run `xcodebuild`, `xcrun`, and Xcode, then diff the

- outputs.

- 4. Binary metadata: ObjC class, protocol, and selector names, Swift type

- names, linked libraries, and the bundle structure.

- 5. Disassembly or decompilation. This is the last resort. Use it only for

- interop-relevant formats or protocols, and record why it was necessary.

- 5. Do not use Apple trademarks or artwork in Ycode's UI or assets.

- Legal context: the Xcode license agreement prohibits reverse engineering

- except where the law permits it. Interoperability exceptions are an

- example (17 U.S.C. §1201(f), EU Directive 2009/24/EC Art. 6). This protocol

- keeps the work within those exceptions. The person who owns this project is

- responsible for making sure that it applies in their jurisdiction. The

- owner describes the project as educational and academic research. The

- protocol stays in force anyway: it documents that the research was done

- properly, and it keeps Ycode's own code independent so that Ycode can be

- released.

- ## Heritage you need to know

- - **NeXTSTEP → OpenStep → Cocoa.** Xcode descends from NeXT's *Project

- Builder*. The `PBX` prefix (`PBXProject`, `PBXNativeTarget`) means Project

- Builder X. The `.pbxproj` file is an OpenStep ASCII property list.

- - **Objective-C runtime.** Xcode has about 15,600 ObjC classes, mostly in

- `IDEKit`, `IDEFoundation`, `DVTFoundation`, and Interface Builder. To read

- these binaries, you must know `objc_msgSend` dispatch, the

- `class_ro_t`/`method_list_t` metadata, categories, KVC/KVO, NSNotification,

- NSDocument, the responder chain, and target–action. Ycode uses Swift

- together with Objective-C where AppKit or runtime interop needs it.

- - **Layering** (from binary linkage):

- - `DVT*`: shared developer-tools foundation and UI kit.

- - `IDEFoundation`: the headless model (workspaces, schemes, the build and

- run system).

- - `IDEKit`: the AppKit UI shell (workspace window, navigators, editors,

- inspectors).

- - `DevToolsCore`/`Xcode3Core`: the legacy project model and pbxproj I/O.

- - Plug-ins (`PlugIns/*.ideplugin`, `*.framework`): extend the shell

- through extension points.

- ## Repository layout

- - `tools/`: our analysis scripts. These record metadata only.

- - `research/inventory/`: the generated bundle inventory (`bundles.json`).

- - `research/notes/`: dirty-room observations in prose, with no code.

- - `specs/`: the clean-room boundary documents. One spec per subsystem or

- format.

- - `docs/`: architecture and roadmap.

- - `ycode/`: the Swift package (implementation).

- ## Machines

- - macOS (arm64): the reference Xcode, black-box probes, and the main

- development machine.

- - Linux test workstation (x86-64): Ubuntu 26.04, Swift 6.4 through swiftly

- (`. ~/.local/share/swiftly/env.sh`). Log in with an SSH key only. Never

- automate password login. Sync with

- `rsync -az --delete --exclude .build ycode/ <user>@<x86-64-linux-host>:Ycode/ycode/`,

- then run `swift build && swift test` there.

- - The Simulator-track host ("the Thor", arm64 Linux): an NVIDIA Jetson Thor,

- Ubuntu 24.04 aarch64, 4 KB pages, 14 cores, 122 GB RAM, KVM and Vulkan.

- Swift 6.4 through swiftly. Log in with an SSH key only. Large data

- (runtime copies, devices, run output) goes on a separate data volume,

- referred to as `$YCODE_DATA` in specs and scripts, never on the system

- disk. If the machine is shared, touch only your own files.

- - Machine-specific hostnames, users and paths stay out of the repository

- (keep them in your local, untracked notes).

- ## Working conventions

- - Run analysis Python with `python3 -I`.

- - Test corpora (real `.pbxproj` files and other samples) are read from local

- paths at test time. They are never copied into the repo. See

- `ycode/README.md`.

- - Every spec ends with an **Evidence** section that lists the evidence level

- (1–5, from rule 4) used for each claim.

+ @AGENTS.md