In @.github/CODEOWNERS:
- Around line 1-2: Update the .github/CODEOWNERS file to broaden review coverage
by adding rules for the important paths referenced in the comment: add entries
for .github/workflows/ (e.g., ".github/workflows/ `@YourTeam`"), the workspace
Cargo.toml (e.g., "Cargo.toml `@YourTeam`"), the crates/ directory (e.g., "crates/
`@YourTeam`"), and a catch-all fallback (e.g., "* `@YourTeam`") so PRs touching
those symbols get auto-requested reviewers; edit the CODEOWNERS file to include
these additional path patterns and appropriate owner handles.

In @.github/copilot-instructions.md:
- Line 23: Replace the Windows-style backslash path in the Cargo install command
so it matches repository conventions: change the string `crates\\shipper-cli` to
use forward slashes (i.e., `crates/shipper-cli`) in the line containing `cargo
install --path crates\\shipper-cli --locked` so the command is consistent and
cross-platform.

In @.github/workflows/ci.yml:
- Around line 12-45: The CI currently runs all verification steps inside one job
named "check" so an early failure in the "Format check" step blocks "Clippy" and
"Tests"; split the monolithic job into separate jobs (e.g., "fmt" for the Format
check, "clippy" for the Clippy step, "tests" for the Tests step, and
"release-build" for Release build) so they can run in parallel and provide
faster feedback, preserve shared setup (Rust install and actions/cache) in each
job or move common setup to a reusable workflow/step to avoid duplication, and
make any dependent job (e.g., "release-build") explicitly depend on "tests"
using needs to keep serial ordering where required.
- Around line 3-6: Add a GitHub Actions concurrency group to the workflow to
cancel superseded runs: insert a top-level concurrency block (using a group name
based on the workflow and branch/PR ref, e.g. referencing github.workflow and
github.head_ref or github.ref) and set cancel-in-progress: true so when multiple
commits trigger the existing on: push / pull_request workflow older runs are
cancelled automatically.

In `@CHANGELOG.md`:
- Around line 1-105: Add repository comparison links for each released version
at the bottom of CHANGELOG.md so version headers link to diffs; add lines like
"[0.2.0]: https://github.com/<ORG>/<REPO>/compare/v0.1.0...v0.2.0" and "[0.1.0]:
https://github.com/<ORG>/<REPO>/releases/tag/v0.1.0" replacing <ORG>/<REPO> and
prior-tag names as appropriate, ensuring the identifiers exactly match the
version headers "[0.2.0]" and "[0.1.0]" so Keep a Changelog tools will resolve
them.

In `@crates/shipper-cli/Cargo.toml`:
- Around line 1-32: Add a [lints] table to the shipper-cli crate's Cargo.toml to
opt into inheriting workspace lints (same pattern used in the shipper crate) so
workspace lint settings are applied to this crate; update the Cargo.toml for the
package named "shipper-cli" to include the [lints] section with inherit = true.

In `@crates/shipper-cli/src/main.rs`:
- Around line 1096-1151: The test run_doctor_supports_absolute_state_dir mutates
CARGO_REGISTRY_TOKEN, CARGO_REGISTRIES_CRATES_IO_TOKEN, and CARGO_HOME before
capturing their "old" values, so restore_env restores the test values instead of
originals; fix by saving the originals (call env::var(...).ok() into
old_registry, old_named, old_home) before any env::set_var/remove_var calls, or
better replace the manual save/restore with an EnvGuard RAII (as used in
auth.rs) that records and restores those three vars around the run_doctor call;
update references in this test to use EnvGuard or reorder the save/set so
restore_env receives the true pre-test values.
- Line 896: Summary: Change run_clean's state_dir parameter from &PathBuf to
&Path to satisfy clippy::ptr_arg. Update the function signature fn
run_clean(state_dir: &Path, workspace_root: &Path, keep_receipt: bool) ->
Result<()> and adjust any internal code that assumed a PathBuf (use
state_dir.as_ref() or state_dir.to_path_buf() only where an owned PathBuf is
truly needed). Also update all call sites that currently pass a &PathBuf to pass
a &Path (e.g., by borrowing the PathBuf as &*buf or using buf.as_path()), and
run cargo clippy to ensure the ptr_arg warning is resolved.
- Around line 455-463: The printed finishability line sets ANSI color via
finishability_color but never resets it, causing color bleed; update the println
that uses rep.finishability / finishability_color / finishability_text to emit
the ANSI reset sequence ("\x1b[0m") after the text (either append the reset to
the selected color string or include it in the println format) so the terminal
color is restored immediately after the finishability text.

In `@crates/shipper-cli/tests/cli_e2e.rs`:
- Around line 302-314: The manual ANSI-stripping folded into the computation of
`stripped` from `normalized` is fragile and should be replaced with a tested
crate function; update the test to call a library like strip-ansi-escapes or
console::strip_ansi_codes on `normalized` instead of the custom fold, add the
chosen crate as a dev-dependency, and assign its result to `stripped` so all
ANSI sequences (not just SGR `\x1b[...m`) are correctly removed.
- Around line 129-149: spawn_registry currently calls server.recv() in the
spawned thread and will block forever (causing registry.join() to hang) if fewer
requests arrive than expected; replace server.recv() with a timed receive (e.g.,
server.recv_timeout(Duration::from_secs(10))) inside the thread loop in
spawn_registry, handle the timeout/error result by returning/panic with a clear
message or breaking the loop so the thread terminates cleanly, and keep the
existing logic that selects status from statuses (refer to spawn_registry,
server.recv(), and TestRegistry.handle) so tests fail fast instead of
deadlocking.

In `@crates/shipper/Cargo.toml`:
- Around line 1-36: Add a [lints] table to this crate's Cargo.toml to inherit
workspace lints by adding a section like `[lints] workspace = true`; this will
pull in the root workspace lints (e.g. the `workspace.lints.rust` settings such
as `unsafe_code = "forbid"`) so the crate respects the workspace lint
configuration.

In `@crates/shipper/src/auth.rs`:
- Around line 58-65: cargo_home_dir currently checks CARGO_HOME then HOME and
errors, which fails on Windows where HOME is often unset; update cargo_home_dir
to also try env::var("USERPROFILE") and, if that is unset, fall back to
combining env::var("HOMEDRIVE") and env::var("HOMEPATH") before returning an
error, and ensure the returned PathBuf uses the chosen value joined with
".cargo" and that the context/error message reflects the additional fallbacks;
refer to the cargo_home_dir function and its env::var calls when making the
change.
- Around line 108-123: The alias lookup loop inside the registry_name ==
"crates-io" branch redundantly includes "crates-io" again; update the loop in
that block (the for alt in [...] that checks registries.{alt}.token) to remove
the "crates-io" entry so it only iterates over the true aliases ("crates.io",
"crates_io"), leaving the explicit crates-io lookup earlier intact.
- Line 67: Change the token_from_credentials_file signature to accept a &Path
instead of &PathBuf: replace the parameter type in fn
token_from_credentials_file(path: &PathBuf, registry_name: &str) ->
Result<Option<String>> with &Path and update any internal uses (e.g.,
path.exists(), path.join(), file opening) to work with &Path; also update call
sites to pass path.as_ref() or a &Path directly and add use std::path::Path if
needed so the function accepts a more general path reference and satisfies
clippy::ptr_arg.

In `@crates/shipper/src/config.rs`:
- Around line 256-303: The validate() method currently misses checks for
readiness backoff timing which can lead to tight CPU spin; add validation inside
Config::validate (or the validate method shown) to ensure readiness.max_delay >
0 and readiness.initial_delay > 0, and also enforce that readiness.initial_delay
<= readiness.max_delay and readiness.initial_delay <= readiness.max_total_wait
(or at minimum initial_delay <= max_total_wait) and bail with clear messages
(e.g., "readiness.max_delay must be greater than 0", "readiness.initial_delay
must be greater than 0", "readiness.initial_delay must be <=
readiness.max_delay", "readiness.initial_delay must be <=
readiness.max_total_wait") so the readiness backoff cannot be zero or cause
tight loops.

In `@crates/shipper/src/engine_parallel.rs`:
- Around line 76-77: The calls to state::save_state in publish_package are
currently silencing errors with "let _ = …"; change each to capture the Result
and on Err call the reporter to log the failure (e.g. match
state::save_state(state_dir, &state) { Ok(_) => {}, Err(e) =>
reporter.error(&format!("failed to save state to {}: {}", state_dir.display(),
e)) }) so persistence failures are visible; apply the same change at every site
where state::save_state is ignored (the calls inside publish_package shown in
the diff) and include the state_dir and the error details in the log message.
- Around line 578-590: Currently SendReporter buffers all messages and replays
them to the real reporter only at the end (the block that locks send_reporter
and iterates sr.infos/sr.warns/sr.errors), which defers all output until the
entire parallel publish finishes; change the code so the same replay logic runs
after each level completes (i.e., after each level's work loop/worker join)
instead of once at the end: locate where levels are processed in
engine_parallel.rs, and after the per-level completion point call the existing
replay code (lock send_reporter, iterate sr.infos/sr.warns/sr.errors and call
reporter.info/warn/error) to flush that level’s messages; alternatively
implement a channel-based forwarder between SendReporter and reporter if you
prefer streaming, but the minimal fix is moving the replay block to run after
every level completion.
- Around line 538-559: SendReporter currently nests Mutexes (infos/warns/errors:
Mutex<Vec<String>>) while the instance is already stored in
Arc<Mutex<SendReporter>> (send_reporter), so remove the inner mutexes: change
SendReporter fields to plain Vec<String>, update the Reporter impl methods
(info/warn/error) to push directly onto the vectors via &mut self (no .lock()),
and adjust the send_reporter construction to initialize Vec::new() for each
field instead of Mutex::new(...). Ensure all usages that previously relied on
inner locks now acquire the outer Mutex (e.g., via send_reporter.lock()) and
mutate the vectors through &mut SendReporter.

In `@crates/shipper/src/engine.rs`:
- Around line 437-597: The loop currently retries when cargo publish exits
successfully but verify_published returns not visible, causing a re-publish;
instead, after a successful cargo publish (the success branch where
out.exit_code == 0), if verify_published reports not visible, mark the package
as Published and exit the loop rather than retrying. Concretely, inside the
success branch after verify_published (the block handling visible == false),
call update_state(&mut st, &state_dir, &key, PackageState::Published)?, clear
last_err, record the PackagePublished PublishEvent and write/clear event_log
(same as the visible==true path), set readiness_evidence appropriately, then
break; ensure you reference verify_published, update_state,
PackageState::Published, event_log.record/ write_to_file/clear, and
readiness_evidence when making the change.

In `@crates/shipper/src/environment.rs`:
- Around line 162-175: The current test
environment_fingerprint_shipper_version_is_set uses a naive char check on
fingerprint.shipper_version which wrongly rejects valid pre-release/build
metadata and accepts malformed strings; update the assertion to validate using a
real semver parser (e.g. semver::Version::parse) or a stricter pattern: call
collect_environment_fingerprint(), get fingerprint.shipper_version and either
assert semver::Version::parse(&fingerprint.shipper_version).is_ok() or assert it
starts with a digit and contains at least one '.' to perform a basic sanity
check (replace the chars().all(...) check accordingly).
- Around line 30-61: Both get_cargo_version and get_rust_version duplicate the
same logic; extract a helper fn get_tool_version(cmd: &str) -> Option<String>
that runs Command::new(cmd).arg("--version").output().ok()?, checks
output.status.success(), reads stdout via String::from_utf8_lossy, and returns
the second whitespace token (.split_whitespace().nth(1).map(|s| s.to_string())).
Then implement get_cargo_version() -> get_tool_version("cargo") and
get_rust_version() -> get_tool_version("rustc") to remove the duplicated parsing
logic.

In `@crates/shipper/src/events.rs`:
- Around line 28-51: write_to_file currently appends the entire in-memory events
Vec (self.events) each call, causing duplicate records unless callers call
clear(); change write_to_file to adopt a flush semantic: after successfully
serializing/writing all events and writer.flush() succeeds, clear the written
events (e.g., call the existing clear() or self.events.clear()) so subsequent
calls only append new events; ensure errors still return without clearing and
add/update tests for write_to_file to verify that a successful write removes
events from memory while failure preserves them.

In `@crates/shipper/src/git.rs`:
- Around line 82-97: The get_git_tag function is incorrectly passing the shell
redirection string "2>/dev/null" as an argument to git; remove the
.arg("2>/dev/null") call so
Command::new(git_program()).arg("describe").arg("--tags").arg("--exact-match").current_dir(repo_root).output()
is used instead, allowing the code to rely on output.status and .ok() to handle
failures; update the call site in get_git_tag accordingly and ensure behavior
(returning None on non-success) remains unchanged.
- Around line 156-180: The EnvGuard test helper is duplicated across five files
(variants A and B); extract it into a single shared #[cfg(test)] test utility
module (e.g., tests/util or a new crate::test_utils mod) and replace the local
copies with imports; implement one unified EnvGuard struct that provides both
set(&str,&str) and unset(&str) methods and derives Clone so it covers both
variants, and ensure Drop restores or removes the env var as before; update
usages in git.rs, engine.rs, engine_parallel.rs, auth.rs, and cargo.rs to use
the shared EnvGuard.
- Around line 11-13: Change collect_git_context to accept repo_root: &Path
instead of calling std::env::current_dir(); replace the current_dir lookup with
using the passed repo_root when constructing repo paths and invoking git
operations inside collect_git_context; update all callers (e.g., the call from
engine where workspace_root is available) to pass their
repo_root/workspace_root, and adjust tests to pass a temporary Path to avoid
mutating CWD so behavior remains consistent with is_git_clean and
ensure_git_clean.

In `@crates/shipper/src/lock.rs`:
- Around line 32-35: LockFile currently defines a dead field `file:
Option<File>` that is always left as None by `LockFile::acquire` and
`LockFile::release`; either remove the field entirely from the `LockFile` struct
and delete any code in `acquire`/`release` that assigns to `self.file`, or if
the intent was to hold the opened file for an advisory lock, change `acquire` to
store the opened File in `self.file = Some(file)` and ensure `release` drops it
(sets to None) and that ownership/locking semantics are correct; update
references in `acquire`, `release`, and any constructors accordingly to match
the chosen approach.
- Around line 43-93: The acquire function currently uses a check-then-create
pattern (lock_path.exists() then create tmp + rename) which allows a TOCTOU
race; change it to create the lock file atomically using OS semantics instead of
the exists() check: remove the preliminary exists() branch and instead attempt
to open/create the lock file atomically (e.g., use
std::fs::OpenOptions::new().create_new(true).write(true).open(&lock_path) or use
fs2::FileExt::try_lock_exclusive on a permanently opened file) and on success
write the serialized LockInfo into that file (or write to a temp and rename only
if you still need content-atomicity, but creation must use create_new or an
exclusive lock). Ensure acquire returns the Lock struct with the held file
handle so the process retains the lock until drop, and map any create_new/open
failures to the existing "lock already held" error path referencing acquire(),
lock_path, and tmp_path as needed.

In `@crates/shipper/src/plan.rs`:
- Around line 283-334: group_by_levels currently assumes self.packages is
topologically ordered which makes level assignment fragile; rewrite
ReleasePlan::group_by_levels to derive levels from self.dependencies in an
order‑independent way (e.g. Kahn's algorithm): build the graph and indegree map
from self.dependencies and all package names, enqueue nodes with indegree 0 as
level 0, pop each node, assign its level into a pkg_level map, then for each
dependent decrement indegree and set dependent_level = max(dependent_level,
current_level + 1) before enqueueing when indegree hits 0; finally collect
PublishLevel structs from the pkg_level map into a Vec<PublishLevel> (ensuring
PublishLevel.level values are consistent) instead of relying on the iteration
over self.packages or the current while/levels logic.
- Around line 64-139: When building dependency edges in the loop over
resolve.nodes (the block that currently fills deps_of/dependents_of), detect if
a publishable package depends on a workspace member that is not in publishable:
for each dep in node.deps (and where dep_kinds contains Normal/Build) if
pkg_map.contains_key(&dep.pkg) && !publishable.contains(&dep.pkg) then return an
error (or otherwise reject/skip) with a clear message naming the publishable
package (node.id or pkg_map.get(&node.id).name) and the non-publishable
workspace dependency (dep.pkg or its name). Add this check before silently
continuing so such invalid publishable crates are reported rather than dropping
the edge.

In `@crates/shipper/src/registry.rs`:
- Around line 133-188: calculate_index_path currently always uses a 2+2+N layout
and parse_version_from_index treats the index as a JSON array; fix both to
follow Cargo's sparse index spec: update calculate_index_path to return
"1/<name>" for len==1, "2/<name>" for len==2, "3/<first>/<name>" for len==3, and
"<first_two>/<second_two>/<name>" for len>=4 (use the first two and next two
characters of crate_name), and update parse_version_from_index to parse
newline-delimited JSON (JSONL) by iterating each non-empty line, deserializing
into the IndexVersion struct and checking vers == version (instead of parsing
the entire content as an array); keep the existing IndexVersion struct and the
same error context when deserialization of a line fails.

In `@crates/shipper/src/state.rs`:
- Around line 199-219: The function atomic_write_json performs fsync on the temp
file but does not fsync the parent directory after fs::rename, so the rename may
be lost on crash; modify atomic_write_json to, after fs::rename(&tmp, path)
succeeds, open the parent directory (using path.parent()) as a File (via
OpenOptions::new().read(true).open(parent_dir) or similar) and call sync_all()
on that directory File, propagating errors with context (e.g., "failed to sync
parent directory ..."); handle the case where path.parent() is None
appropriately and include with_context messages consistent with existing error
handling.

In `@crates/shipper/src/store.rs`:
- Around line 72-83: The check in parse_schema_version is too permissive and the
middle segment isn't validated; change the prefix check from
parts[0].starts_with("shipper") to an exact equality check parts[0] == "shipper"
and add validation for parts[1] (the schema type) — either assert it matches
allowed values like "receipt" or "state" or change parse_schema_version to
return the middle segment alongside the numeric version so callers can enforce
type consistency (update callers such as validate_schema_version accordingly).

In `@crates/shipper/src/types.rs`:
- Around line 57-66: The current get_index_base method uses naive string
replacement on api_base which breaks for hosts with paths or already-indexed
hosts; update get_index_base to parse self.api_base as a URL (e.g., using
url::Url), then construct the index base by prefixing "index." to the parsed
host (unless the host already contains "index." or an explicit self.index_base
is set) and preserve the scheme and any port but omit path/segments, falling
back to returning the original self.index_base.clone() when provided; ensure
get_index_base handles parse errors by falling back to a sensible default
(original api_base or self.index_base) and document the behavior.

In `@docs/preflight.md`:
- Around line 61-90: Add the language specifier "text" to the fenced code blocks
used for sample output: change the triple-backtick fences that wrap the
"Preflight Report" block (the block starting with "Preflight Report" and showing
Plan ID, Token Detected, Packages table, Summary, and "What to do next:"), and
the other similar fenced blocks later in the file that show sample CLI/output
examples, to use ```text so markdown linters/renderers recognize them as plain
text output.

In `@docs/readiness.md`:
- Around line 184-216: Consolidate the duplicate troubleshooting content by
merging the "Index checks are slow" section into "Readiness checks are slow" to
eliminate redundancy: keep a single "Readiness checks are slow" heading (and
mention index-specific note inside it) that contains the shared causes and
solutions (recommend `--readiness-method api`, `--readiness-poll`,
`--readiness-timeout`, and local index mirror), remove the separate "Index
checks are slow" block, update any cross-references/TOC entries to point to the
unified section, and ensure the "Readiness checks fail even though crate was
published" section still references both methods/timeout as before.
- Around line 157-168: The fenced pseudocode blocks that show retry delays are
missing language specifiers; update both code fences that contain the "Attempt
1: delay = initial_delay" block and the "actual_delay = delay * (1 ±
jitter_factor)" line to include a language tag (use "text") so the fences become
```text ... ``` to satisfy markdownlint MD040.

In `@fuzz/fuzz_targets/resolve_token.rs`:
- Around line 20-24: Save the original environment state before mutating it and
restore after the call to resolve_token("crates-io") by adopting the EnvGuard
pattern used elsewhere: capture current values of CARGO_HOME,
CARGO_REGISTRY_TOKEN and CARGO_REGISTRIES_CRATES_IO_TOKEN, set/remove them for
the fuzz iteration, call resolve_token, then restore the saved values (or remove
if previously absent) in a drop/guard so restoration happens even on panic;
locate this logic around the resolve_token invocation in resolve_token.rs and
mirror the EnvGuard behavior from the EnvGuard implementation used in
git.rs/engine.rs.

In `@GEMINI.md`:
- Line 40: Remove the trailing space after the bold heading "**Testing
Pattern:**" to satisfy MD009; edit the line containing "**Testing Pattern:** "
(the bold heading) and delete the extra space at the end (or intentionally
replace with two spaces only if you want a hard line break), ensuring no other
trailing whitespace remains on that line.

In `@LICENSE-MIT`:
- Line 3: Update the MIT license header to include the copyright holder name by
replacing the current "Copyright (c) 2026" line with a complete notice that
includes the holder (for example: "Copyright (c) 2026 EffortlessMetrics" or the
project's author/organization name); ensure the holder name is the official
entity owning the code and matches other project metadata.

In `@RELEASE_CHECKLIST_v0.2.0.md`:
- Around line 5-16: Update the inconsistent test counts in the release checklist
by changing the numbers in the top checklist and the "Code Quality Checks" block
to match the PR summary (replace "229 lib + 13 CLI unit + 20 E2E" and "262
total: 229 lib, 13 CLI unit, 20 CLI E2E" with the PR-reported counts, e.g., "247
lib" and the correct total "280 total" and adjust the breakdown accordingly);
edit the lines that contain the literal backticked commands/labels "Run `cargo
test --workspace` — all passing (229 lib + 13 CLI unit + 20 E2E)" and the "All
tests pass (262 total: 229 lib, 13 CLI unit, 20 CLI E2E)" text to the updated
numbers so the checklist and Code Quality Checks section are consistent.
- Around line 63-67: The checklist item "- [ ] Publish to crates.io:" contains a
fenced code block (```bash ... cargo publish -p shipper-cli ``` ) that lacks
blank lines before and after the block; update the Markdown to add a blank line
between the list item text and the opening ```bash, and another blank line after
the closing ``` so the fenced code block is separated from surrounding list
items (ensure the opening ```bash and closing ``` remain intact and the two
cargo publish lines are unchanged).

In `@templates/github-trusted-publishing.yml`:
- Line 30: Update the workflow steps that reference actions/cache and
actions/upload-artifact to use the v4 releases to match the other v4 actions;
specifically replace uses: actions/cache@v3 with actions/cache@v4 and uses:
actions/upload-artifact@v3 with actions/upload-artifact@v4, then commit and
validate the workflow syntax by running the GitHub Actions linter or a test run
to ensure compatibility with actions/checkout@v4 and
actions/download-artifact@v4.

In `@templates/gitlab-publish.yml`:
- Line 5: Update the Docker image tag used in the CI template: replace the
hardcoded image reference "image: rust:1.75" with the project's MSRV "rust:1.92"
so the job uses Rust 1.92 (locate the `image:` line in the gitlab CI template
where `rust:1.75` is declared and change it to `rust:1.92`).