Document semantic comparison baseline and toolchain blockers

1 files changed, 70 insertions, 0 deletions

diff --git a/docs/legacy-comparison.md b/docs/legacy-comparison.md
new file mode 100644
index 0000000..75d3bb1
--- /dev/null
+++ b/docs/legacy-comparison.md
@@ -0,0 +1,70 @@
+# Legacy comparison status
+
+## Current native semantic-comparison baseline
+
+The native builder can collect portable semantic facts directly from either a
+rootfs tar archive or its companion manifest and compare:
+
+- package name/version records when supplied by a build manifest;
+- regular-file SHA-256 digests, symlinks, and hardlinks;
+- RT initrd path and SHA-256 digest;
+- enabled systemd service symlinks; and
+- archive member paths and kinds.
+
+Legacy tar paths using a leading `./` are normalized before comparison. Hasher
+metadata paths containing `.host` or `.fakedata` are excluded on both sides.
+This comparison deliberately does not claim byte-for-byte tar equivalence.
+
+Validated native plan command:
+
+```text
+$ cargo run -- plan --spec profiles/alt-controller.toml
+target: alt-controller
+architecture: x86_64
+format: tar
+stages:
+  1. resolve
+  2. install
+  3. finalize-rootfs
+  4. initramfs
+  5. package
+  6. manifest
+```
+
+## Current blocker: unavailable Clippy component
+
+The required lint and formatting validations cannot run in the installed Rust
+toolchain. Exact command output from this workspace:
+
+```text
+$ cargo clippy -- -D warnings
+error: no such command: `clippy`
+
+help: view all installed commands with `cargo --list`
+help: find a package to install `clippy` with `cargo search cargo-clippy`
+
+$ cargo fmt --check
+error: no such command: `fmt`
+
+help: a command with a similar name exists: `fix`
+
+help: view all installed commands with `cargo --list`
+help: find a package to install `fmt` with `cargo search cargo-fmt`
+```
+
+`cargo test` completed successfully before the formatting command (39
+integration tests), and `cargo build --release` succeeds. The corrective action
+is to install the Clippy and rustfmt components/packages for this toolchain,
+then run:
+
+```text
+cargo clippy -- -D warnings
+cargo fmt --check
+```
+
+## Next comparison action
+
+Produce a native Controller artifact in an isolated workspace, collect its
+companion manifest, and run `alt-controller-image compare` against the observed
+legacy Controller tarball. Record every semantic delta as deliberate or
+unresolved in this document.