docs(todo): retag TODO markers by root cause

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

25 files changed, 48 insertions, 48 deletions

diff --git a/crates/shirabe/src/advisory/audit_config.rs b/crates/shirabe/src/advisory/audit_config.rs
index fc1cbedb..2d01a4a9 100644
--- a/crates/shirabe/src/advisory/audit_config.rs
+++ b/crates/shirabe/src/advisory/audit_config.rs
@@ -83,7 +83,7 @@ impl AuditConfig {
         for (key, value) in entries {
             let (id, apply, reason) = match value {
                 PhpMixed::String(reason_str) => {
-                    // TODO(phase-e): PHP's `array` type must be modeled more precisely. This is
+                    // TODO(type-model): PHP's `array` type must be modeled more precisely. This is
                     // escape hatch.
                     if canonical_int_key(key).is_some() {
                         (reason_str.clone(), "all".to_string(), None)
diff --git a/crates/shirabe/src/command/diagnose_command.rs b/crates/shirabe/src/command/diagnose_command.rs
index dc5d7399..6b339c69 100644
--- a/crates/shirabe/src/command/diagnose_command.rs
+++ b/crates/shirabe/src/command/diagnose_command.rs
@@ -599,7 +599,7 @@ impl DiagnoseCommand {
             None,
         )?;
         if !installed_json.exists() {
-            // TODO(phase-c): the native binary never ships vendor/composer/installed.json, so
+            // TODO(distribution): the native binary never ships vendor/composer/installed.json, so
             // Composer's "non-standard Composer installation" warning would fire on every run.
             // A Composer source snapshot is planned to be embedded together with the plugin API
             // implementation, which will make this self-audit functional; until then report
diff --git a/crates/shirabe/src/command/script_alias_command.rs b/crates/shirabe/src/command/script_alias_command.rs
index e4418b53..b10e1671 100644
--- a/crates/shirabe/src/command/script_alias_command.rs
+++ b/crates/shirabe/src/command/script_alias_command.rs
@@ -46,7 +46,7 @@ impl ScriptAliasCommand {
 
         // PHP also calls parent::__construct() (Symfony Command base) and
         // $this->ignoreValidationErrors().
-        // TODO(phase-c): both are Symfony Command base-class operations — the constructor sets up
+        // TODO(symfony): both are Symfony Command base-class operations — the constructor sets up
         // the command's name/definition/application state and ignoreValidationErrors() flips a flag
         // on it. Composer's BaseCommand carries no such Symfony Command state yet (the Symfony
         // Command base is an intentional todo!() stub), so there is nothing to initialize here.
@@ -118,7 +118,7 @@ impl Command for ScriptAliasCommand {
 
         let args = input.borrow().get_arguments();
 
-        // TODO(phase-c): InputInterface has_to_string/get_class_name not modeled in Rust
+        // TODO(symfony): InputInterface has_to_string/get_class_name not modeled in Rust
         // TODO remove for Symfony 6+ as it is then in the interface
         if false {
             return Err(LogicException::new(
@@ -136,7 +136,7 @@ impl Command for ScriptAliasCommand {
 
         Platform::put_env("COMPOSER_DEV_MODE", if dev_mode { "1" } else { "0" });
 
-        // TODO(phase-c): InputInterface lacks to_string; use a placeholder until it is modeled.
+        // TODO(symfony): InputInterface lacks to_string; use a placeholder until it is modeled.
         let input_as_string = String::new();
         let _ = input;
         let script_alias_input = Preg::replace4(php_regex!(r"{^\S+ ?}"), "", &input_as_string, 1);
diff --git a/crates/shirabe/src/command/search_command.rs b/crates/shirabe/src/command/search_command.rs
index 72a883f1..e66c574b 100644
--- a/crates/shirabe/src/command/search_command.rs
+++ b/crates/shirabe/src/command/search_command.rs
@@ -260,7 +260,7 @@ impl Command for SearchCommand {
                 }
             }
         } else if format == "json" {
-            // TODO(phase-c): faithful JSON output requires SearchResult to retain the raw result
+            // TODO(type-model): faithful JSON output requires SearchResult to retain the raw result
             // array. PHP's fulltext search passes through arbitrary API fields (downloads, favers,
             // repository, ...) which the typed SearchResult (name/description/abandoned/url) drops,
             // so ComposerRepository-sourced results still diverge from Composer's raw JSON output.
diff --git a/crates/shirabe/src/composer.rs b/crates/shirabe/src/composer.rs
index 2bf59d8b..e714f85d 100644
--- a/crates/shirabe/src/composer.rs
+++ b/crates/shirabe/src/composer.rs
@@ -14,7 +14,7 @@ use crate::util::r#loop::Loop;
 use shirabe_pcre::Preg;
 use shirabe_php_shim::php_regex;
 
-// TODO(phase-c): change this information to Shirabe version.
+// TODO(distribution): change this information to Shirabe version.
 pub const VERSION: &str = "2.9.7";
 pub const BRANCH_ALIAS_VERSION: &str = "";
 pub const RELEASE_DATE: &str = "2026-04-14 13:31:52";
diff --git a/crates/shirabe/src/console/application.rs b/crates/shirabe/src/console/application.rs
index fa9f7edd..56947243 100644
--- a/crates/shirabe/src/console/application.rs
+++ b/crates/shirabe/src/console/application.rs
@@ -1345,7 +1345,7 @@ impl Application {
             // PHP rewrites `@anonymous\0` markers via class_exists/get_parent_class/class_implements.
             // Rust error messages never carry PHP's anonymous-class marker and those reflection
             // primitives have no Rust equivalent, so the branch is unreachable here.
-            // TODO(phase-c): port the @anonymous rewrite if it ever becomes relevant.
+            // TODO(port): port the @anonymous rewrite if it ever becomes relevant.
 
             let width = if self.terminal.get_width() != 0 {
                 self.terminal.get_width() - 1
@@ -1371,7 +1371,7 @@ impl Application {
             if !throwable_is_exception_interface(e)
                 || output_interface::VERBOSITY_VERBOSE <= verbosity
             {
-                // TODO(phase-c): anyhow::Error carries no PHP file/line, so getFile()/getLine() take
+                // TODO(error-model): anyhow::Error carries no PHP file/line, so getFile()/getLine() take
                 // the 'n/a' fallback PHP itself uses when they are unavailable. The real source
                 // location cannot be reproduced (it would be a Rust path, not Composer's PHP path).
                 messages.push(format!(
diff --git a/crates/shirabe/src/event_dispatcher/event_dispatcher.rs b/crates/shirabe/src/event_dispatcher/event_dispatcher.rs
index d9ec9306..368e2227 100644
--- a/crates/shirabe/src/event_dispatcher/event_dispatcher.rs
+++ b/crates/shirabe/src/event_dispatcher/event_dispatcher.rs
@@ -346,7 +346,7 @@ impl EventDispatcher {
             // other newly appeared prepended autoloaders should be appended instead to ensure Composer loads its classes first
             // PHP: spl_autoload_unregister($cb); spl_autoload_register($cb, true, $prepend);
             // TODO(plugin): ClassLoader detection via instanceof — currently treat all callbacks uniformly
-            // TODO(phase-c): `cb` is a PhpMixed holding a callable; spl_autoload_register/unregister
+            // TODO(php-runtime): `cb` is a PhpMixed holding a callable; spl_autoload_register/unregister
             // (php-shims that stay todo!()) need a typed Box<dyn Fn(&str) -> PhpMixed> callback.
             // Bridging requires the callable model to expose the underlying closure from PhpMixed.
             let _ = &cb;
diff --git a/crates/shirabe/src/factory.rs b/crates/shirabe/src/factory.rs
index 926ca380..4fe248c5 100644
--- a/crates/shirabe/src/factory.rs
+++ b/crates/shirabe/src/factory.rs
@@ -878,7 +878,7 @@ impl Factory {
             // once everything is initialized we can
             // purge packages from local repos if they have been deleted on the filesystem
             // PHP: $this->purgePackages($rm->getLocalRepository(), $im);
-            // TODO(phase-c): purge_packages' removal body (repo.removePackage for packages
+            // TODO(port): purge_packages' removal body (repo.removePackage for packages
             // deleted on the filesystem) is still a stub; wire this call once implemented.
             // self.purge_packages(&InstalledRepositoryInterfaceHandle::from_repository_handle(&rm.get_local_repository()), &mut im)?;
         }
diff --git a/crates/shirabe/src/installer/installation_manager.rs b/crates/shirabe/src/installer/installation_manager.rs
index 8c26bdbc..2d21fb54 100644
--- a/crates/shirabe/src/installer/installation_manager.rs
+++ b/crates/shirabe/src/installer/installation_manager.rs
@@ -839,7 +839,7 @@ impl InstallationManager {
             return;
         }
 
-        // TODO(phase-c): PHP collects every http_downloader.add() promise and runs them via
+        // TODO(async): PHP collects every http_downloader.add() promise and runs them via
         // Loop::wait; the single-threaded sync bridge block_on's each notification serially instead.
         let result: anyhow::Result<()> = (|| -> anyhow::Result<()> {
             for (repo_url, packages) in self.notifiable_packages.borrow().iter() {
@@ -966,7 +966,7 @@ impl InstallationManager {
 
     /// PHP: waitOnPromises() creates a ProgressBar up front and Loop::wait advances it while the
     /// concurrent promises resolve.
-    /// TODO(phase-c): Loop::wait has no active-job counter to feed the bar yet, so a
+    /// TODO(async): Loop::wait has no active-job counter to feed the bar yet, so a
     /// single 0% -> 100% jump is rendered after the wait instead of PHP's timing-driven
     /// intermediate snapshots.
     async fn wait_on_promises<'p>(
diff --git a/crates/shirabe/src/io/console_io.rs b/crates/shirabe/src/io/console_io.rs
index 060fa0c6..6e78a105 100644
--- a/crates/shirabe/src/io/console_io.rs
+++ b/crates/shirabe/src/io/console_io.rs
@@ -310,7 +310,7 @@ impl ConsoleIO {
     }
 
     /// Ensures a string is valid UTF-8, replacing invalid byte sequences with '?'
-    // TODO(phase-c): PHP sanitizes invalid byte sequences here, but `&str` is always valid UTF-8
+    // TODO(bytes): PHP sanitizes invalid byte sequences here, but `&str` is always valid UTF-8
     // so this is a no-op for now. The codebase does not yet strictly distinguish `Vec<u8>` from
     // `String`; once it does, this should take `&[u8]` and lossily convert it to `String`.
     fn ensure_valid_utf8(string: &str) -> String {
@@ -438,7 +438,7 @@ impl IOInterfaceImmutable for ConsoleIO {
         self.ask_question(&question)
     }
 
-    // TODO(phase-c): ask_confirmation and ask_and_hide_answer still collapse ask_question
+    // TODO(error-model): ask_confirmation and ask_and_hide_answer still collapse ask_question
     // errors with .expect() instead of propagating them; extending Result propagation to
     // them is a further IOInterface signature change that has not been decided yet.
     fn ask_confirmation(&self, question: String, default: bool) -> bool {
diff --git a/crates/shirabe/src/json/json_file.rs b/crates/shirabe/src/json/json_file.rs
index 86dc0a2b..652f1d89 100644
--- a/crates/shirabe/src/json/json_file.rs
+++ b/crates/shirabe/src/json/json_file.rs
@@ -517,10 +517,10 @@ impl JsonFile {
     /// @throws ParsingException
     /// @return bool                      true on success
     pub(crate) fn validate_syntax(json: &str, file: Option<&str>) -> anyhow::Result<bool> {
-        // TODO(phase-c): make json_decode() returns an error object with details.
+        // TODO(php-semantics): make json_decode() returns an error object with details.
         let error = match serde_json::from_str::<serde_json::Value>(json) {
             Ok(_) => {
-                // TODO(phase-c): Rust's &str is guaranteed as UTF-8, but PHP string is not. Change `json`
+                // TODO(bytes): Rust's &str is guaranteed as UTF-8, but PHP string is not. Change `json`
                 // to &[u8] and check UTF-8 validity here.
 
                 // if (defined('JSON_ERROR_UTF8') && JSON_ERROR_UTF8 === json_last_error()) {
diff --git a/crates/shirabe/src/main.rs b/crates/shirabe/src/main.rs
index f8b64c46..c4d9d313 100644
--- a/crates/shirabe/src/main.rs
+++ b/crates/shirabe/src/main.rs
@@ -42,7 +42,7 @@ fn main() {
     // here (rather than driving `run` via `.block_on`) just makes it ambiently available via
     // `Handle::try_current()` for `util::sync_executor::block_on`'s many scattered call sites,
     // which ride it through `tokio::task::block_in_place` instead of each spinning up (or
-    // busy-spin-polling without) their own. See sync_executor.rs for the TODO(phase-e) tracking
+    // busy-spin-polling without) their own. See sync_executor.rs for the TODO(async) tracking
     // the eventual goal of propagating `async fn` all the way up to here instead.
     let runtime = tokio::runtime::Builder::new_multi_thread()
         .enable_all()
diff --git a/crates/shirabe/src/plugin/php_plugin_proxy.rs b/crates/shirabe/src/plugin/php_plugin_proxy.rs
index 4edc76ce..9a93ef72 100644
--- a/crates/shirabe/src/plugin/php_plugin_proxy.rs
+++ b/crates/shirabe/src/plugin/php_plugin_proxy.rs
@@ -291,7 +291,7 @@ impl RustMethodDispatcher for PluginRpcDispatcher<'_> {
         if rhandle == 0 {
             if method_name == "__shirabe_find_file" {
                 let class = match args.first() {
-                    // TODO(phase-e): lossy UTF-8; class names are bytes in PHP.
+                    // TODO(bytes): lossy UTF-8; class names are bytes in PHP.
                     Some(PluginValue::String(bytes)) => String::from_utf8_lossy(bytes).into_owned(),
                     other => {
                         return Err(runtime_throw(format!(
@@ -307,7 +307,7 @@ impl RustMethodDispatcher for PluginRpcDispatcher<'_> {
             if method_name == "__shirabe_run_rust_command" {
                 let (name, input_line) = match (args.first(), args.get(1)) {
                     (Some(PluginValue::String(name)), Some(PluginValue::String(line))) => (
-                        // TODO(phase-e): lossy UTF-8; command lines are bytes in PHP.
+                        // TODO(bytes): lossy UTF-8; command lines are bytes in PHP.
                         String::from_utf8_lossy(name).into_owned(),
                         String::from_utf8_lossy(line).into_owned(),
                     ),
@@ -393,7 +393,7 @@ impl RustMethodDispatcher for PluginRpcDispatcher<'_> {
 /// ends up holding a second, unconnected instance of a Composer service.
 pub(crate) fn construct_entity(args: &[PluginValue]) -> Result<PluginValue, PhpThrow> {
     let (class, ctor_args) = match (args.first(), args.get(1)) {
-        // TODO(phase-e): lossy UTF-8; class names are bytes in PHP.
+        // TODO(bytes): lossy UTF-8; class names are bytes in PHP.
         (Some(PluginValue::String(class)), Some(PluginValue::List(ctor_args))) => {
             (String::from_utf8_lossy(class).into_owned(), ctor_args)
         }
@@ -700,7 +700,7 @@ fn dispatch_config_method(
 ) -> Result<PluginValue, PhpThrow> {
     let key = |position: usize| -> Result<String, PhpThrow> {
         match args.get(position) {
-            // TODO(phase-e): lossy UTF-8; config keys are bytes in PHP.
+            // TODO(bytes): lossy UTF-8; config keys are bytes in PHP.
             Some(PluginValue::String(bytes)) => Ok(String::from_utf8_lossy(bytes).into_owned()),
             other => Err(runtime_throw(format!(
                 "{method_name} expects a string key, got {other:?}"
@@ -790,7 +790,7 @@ fn dispatch_download_manager_method(
 ) -> Result<PluginValue, PhpThrow> {
     let string_arg = |position: usize| -> Result<String, PhpThrow> {
         match args.get(position) {
-            // TODO(phase-e): lossy UTF-8; paths and types are bytes in PHP.
+            // TODO(bytes): lossy UTF-8; paths and types are bytes in PHP.
             Some(PluginValue::String(bytes)) => Ok(String::from_utf8_lossy(bytes).into_owned()),
             other => Err(runtime_throw(format!(
                 "{method_name} expects a string argument at position {position}, got {other:?}"
@@ -2013,7 +2013,7 @@ fn decode_write_args(
     method_name: &str,
     args: &[PluginValue],
 ) -> Result<(Vec<String>, bool, i64), PhpThrow> {
-    // TODO(phase-e): lossy UTF-8; IO messages are bytes in PHP.
+    // TODO(bytes): lossy UTF-8; IO messages are bytes in PHP.
     let messages = match args.first() {
         Some(PluginValue::String(bytes)) => vec![String::from_utf8_lossy(bytes).into_owned()],
         Some(PluginValue::List(items)) => {
@@ -2289,7 +2289,7 @@ fn decode_subscribed_events(
     };
     let mut events: IndexMap<String, SubscribedEventEntry> = IndexMap::new();
     for (event_name, params) in entries {
-        // TODO(phase-e): lossy UTF-8; event and method names are bytes in PHP.
+        // TODO(bytes): lossy UTF-8; event and method names are bytes in PHP.
         let event_name = String::from_utf8_lossy(&event_name).into_owned();
         let entry = match &params {
             PluginValue::String(method) => {
diff --git a/crates/shirabe/src/plugin/plugin_manager.rs b/crates/shirabe/src/plugin/plugin_manager.rs
index 0667c6a9..1d8e6192 100644
--- a/crates/shirabe/src/plugin/plugin_manager.rs
+++ b/crates/shirabe/src/plugin/plugin_manager.rs
@@ -430,7 +430,7 @@ impl PluginManager {
                 let path = class_loader.find_file(&class).unwrap_or_else(|| {
                     panic!("plugin class `{class}` is already defined but has no autoloadable file")
                 });
-                // TODO(phase-e): file_get_contents is lossy UTF-8; the eval'd plugin source
+                // TODO(bytes): file_get_contents is lossy UTF-8; the eval'd plugin source
                 // should be carried as bytes.
                 let code = file_get_contents(&path)
                     .unwrap_or_else(|| panic!("unable to read the plugin class file `{path}`"));
diff --git a/crates/shirabe/src/repository/composer_repository.rs b/crates/shirabe/src/repository/composer_repository.rs
index b841d5d3..6a1b16ca 100644
--- a/crates/shirabe/src/repository/composer_repository.rs
+++ b/crates/shirabe/src/repository/composer_repository.rs
@@ -973,7 +973,7 @@ impl ComposerRepository {
             // then does a single `$this->loop->wait($promises)`; mirror that here by polling all
             // downloads concurrently via FuturesOrdered (submission order preserved) before doing
             // any of the per-name response processing below.
-            // TODO(phase-c): the fan-out below is structurally concurrent, but each
+            // TODO(async): the fan-out below is structurally concurrent, but each
             // `start_cached_async_download` future still resolves through `HttpDownloader::add`'s
             // `curl_runtime()`/`sync_executor::block_on` bridge, so real I/O overlap does not happen
             // yet (see util/loop.rs::wait). That only changes once a single top-level Runtime
@@ -1765,7 +1765,7 @@ impl ComposerRepository {
         // does a single `$this->loop->wait($promises)`; mirror that here by polling all downloads
         // concurrently via FuturesOrdered (submission order preserved) before doing any of the
         // per-name response processing below.
-        // TODO(phase-c): the fan-out below is structurally concurrent, but each
+        // TODO(async): the fan-out below is structurally concurrent, but each
         // `start_cached_async_download` future still resolves through `HttpDownloader::add`'s
         // `curl_runtime()`/`sync_executor::block_on` bridge, so real I/O overlap does not happen yet
         // (see util/loop.rs::wait). That only changes once a single top-level Runtime replaces those
diff --git a/crates/shirabe/src/repository/platform_repository.rs b/crates/shirabe/src/repository/platform_repository.rs
index feb9388f..e43892a0 100644
--- a/crates/shirabe/src/repository/platform_repository.rs
+++ b/crates/shirabe/src/repository/platform_repository.rs
@@ -1594,7 +1594,7 @@ impl PlatformRepository {
         ));
         let mut extra: IndexMap<String, PhpMixed> = IndexMap::new();
         extra.insert("config.platform".to_string(), PhpMixed::Bool(true));
-        // NOTE(phase-c): neither PackageInterface nor CompletePackageInterface exposes
+        // TODO(type-model): neither PackageInterface nor CompletePackageInterface exposes
         // setExtra (PHP defines it on BasePackage), and the handle API does not surface
         // it. Disabled packages are always plain CompletePackage objects, so reach the
         // concrete Package through the shared Rc.
diff --git a/crates/shirabe/src/repository/vcs_repository.rs b/crates/shirabe/src/repository/vcs_repository.rs
index e0724cd8..4da3f0ad 100644
--- a/crates/shirabe/src/repository/vcs_repository.rs
+++ b/crates/shirabe/src/repository/vcs_repository.rs
@@ -34,7 +34,7 @@ use shirabe_php_shim::{
 };
 use shirabe_semver::constraint::SimpleConstraint;
 
-// TODO(phase-c): the driver registration should be refactored later.
+// TODO(port): the driver registration should be refactored later.
 #[derive(Debug)]
 pub struct VcsRepository {
     pub(crate) inner: ArrayRepository,
diff --git a/crates/shirabe/src/signal.rs b/crates/shirabe/src/signal.rs
index a4765e59..26297cc7 100644
--- a/crates/shirabe/src/signal.rs
+++ b/crates/shirabe/src/signal.rs
@@ -62,7 +62,7 @@ impl Default for SignalSubscription {
 }
 
 impl SignalSubscription {
-    // TODO(phase-c): Windows delivers console control events (CTRL_C_EVENT, CTRL_BREAK_EVENT)
+    // TODO(windows): Windows delivers console control events (CTRL_C_EVENT, CTRL_BREAK_EVENT)
     // rather than signals, and they are not subscribed to here.
     pub fn new() -> Self {
         let seq = SIGNAL_SEQ.load(std::sync::atomic::Ordering::SeqCst);
diff --git a/crates/shirabe/src/util/filesystem.rs b/crates/shirabe/src/util/filesystem.rs
index 2db41238..6cb33385 100644
--- a/crates/shirabe/src/util/filesystem.rs
+++ b/crates/shirabe/src/util/filesystem.rs
@@ -118,7 +118,7 @@ impl Filesystem {
     /// Uses the process component if proc_open is enabled on the PHP
     /// installation.
     pub fn remove_directory(&mut self, directory: impl AsRef<Path>) -> anyhow::Result<bool> {
-        // TODO(phase-c):
+        // TODO(bytes):
         // This path is matched against a regex (remove_edge_cases) and passed to an
         // `rm -rf`/`rmdir` subprocess via the String-based ProcessExecutor, so it has to be
         // representable as UTF-8.
@@ -487,7 +487,7 @@ impl Filesystem {
             return Ok(());
         }
 
-        // TODO(phase-c):
+        // TODO(bytes):
         // The fallbacks below (copy_then_remove and the mv/xcopy subprocesses) operate on
         // path strings, so beyond this point the paths have to be representable as UTF-8.
         let source = source.to_str().ok_or_else(|| {
diff --git a/crates/shirabe/src/util/http/curl_downloader.rs b/crates/shirabe/src/util/http/curl_downloader.rs
index bd77f75e..ff59266e 100644
--- a/crates/shirabe/src/util/http/curl_downloader.rs
+++ b/crates/shirabe/src/util/http/curl_downloader.rs
@@ -11,7 +11,7 @@
 //! is preserved. Per-request TLS/proxy/IP-resolve settings that reqwest only exposes per-Client
 //! are simplified to a single default Client; see the TODOs below.
 //!
-//! TODO(phase-c): `abortRequest()` (PHP `CurlDownloader::abortRequest`, called from
+//! TODO(async): `abortRequest()` (PHP `CurlDownloader::abortRequest`, called from
 //! `HttpDownloader.php:275` when a React\Promise consumer cancels a download) has no equivalent
 //! here: shirabe has never ported the Promise/canceler machinery (`HttpDownloader::STATUS_ABORTED`
 //! is likewise unused), and there is no job table left to cancel now that `download()` runs to
@@ -76,9 +76,9 @@ impl CurlDownloader {
         //   - cookie_store(true)        ~ CURL_LOCK_DATA_COOKIE
         //   - redirect(none)            ~ CURLOPT_FOLLOWLOCATION = false (we follow manually)
         // The libcurl version-specific multiplexing / accept-encoding workarounds are not needed.
-        // TODO(phase-e): a brand-new reqwest client is created per CurlDownloader; that is acceptable here
+        // TODO(http): a brand-new reqwest client is created per CurlDownloader; that is acceptable here
         // (one HttpDownloader owns one CurlDownloader) but not pooled across them.
-        // TODO(phase-c): cookie sharing (CURL_LOCK_DATA_COOKIE) would need reqwest's `cookies` feature
+        // TODO(http): cookie sharing (CURL_LOCK_DATA_COOKIE) would need reqwest's `cookies` feature
         // (.cookie_store(true)); omitted as it is not required for package downloads.
         let client = reqwest::Client::builder()
             .pool_max_idle_per_host(8)
@@ -493,10 +493,10 @@ impl CurlDownloader {
             .and_then(|v| v.as_int())
             .map(|n| n as u64);
 
-        // TODO(phase-c): per-request ssl (cafile/verify_peer/local_cert) and proxy settings are reqwest
+        // TODO(http): per-request ssl (cafile/verify_peer/local_cert) and proxy settings are reqwest
         // Client-level, not request-level. They are not applied here yet; a ConnectionOptions-keyed
         // Client cache (as in the design sketch) is required to honor them.
-        // TODO(phase-c): CURLOPT_IPRESOLVE (force IPv4/IPv6) has no direct reqwest API.
+        // TODO(http): CURLOPT_IPRESOLVE (force IPv4/IPv6) has no direct reqwest API.
         let _ = attributes;
 
         let reqwest_method =
diff --git a/crates/shirabe/src/util/http_downloader.rs b/crates/shirabe/src/util/http_downloader.rs
index 0aa589ca..c8fb943b 100644
--- a/crates/shirabe/src/util/http_downloader.rs
+++ b/crates/shirabe/src/util/http_downloader.rs
@@ -475,7 +475,7 @@ impl HttpDownloader {
             http_map.insert("follow_location".to_string(), PhpMixed::Bool(false));
             http_map.insert("ignore_errors".to_string(), PhpMixed::Bool(true));
             ctx_options.insert("http".to_string(), PhpMixed::Array(http_map));
-            // TODO(phase-c): file_get_contents only takes a path; the stream context arg is dropped
+            // TODO(http): file_get_contents only takes a path; the stream context arg is dropped
             // until the PHP stream-context layer is modeled.
             let _ = stream_context_create(&ctx_options, None);
             let test_connectivity = file_get_contents("https://8.8.8.8");
diff --git a/crates/shirabe/src/util/loop.rs b/crates/shirabe/src/util/loop.rs
index 5d2845c1..dccf5325 100644
--- a/crates/shirabe/src/util/loop.rs
+++ b/crates/shirabe/src/util/loop.rs
@@ -49,7 +49,7 @@ impl Loop {
         let mut pending: FuturesUnordered<_> = promises.into_iter().collect();
         let mut uncaught: Option<anyhow::Error> = None;
 
-        // TODO(phase-c): promises are now polled concurrently via FuturesUnordered, but
+        // TODO(async): promises are now polled concurrently via FuturesUnordered, but
         // each individual future (HttpDownloader::add/add_copy etc.) still resolves through a
         // blocking bridge (curl_runtime()/sync_executor::block_on), so real I/O overlap does not
         // happen yet — the bridged future fully blocks the thread until it settles before the next
@@ -67,7 +67,7 @@ impl Loop {
     }
 
     pub fn abort_jobs(&self) {
-        // TODO(phase-c): no-op until a cancellation mechanism is introduced. PHP cancels
+        // TODO(async): no-op until a cancellation mechanism is introduced. PHP cancels
         // every in-flight promise group it tracks in $currentPromises; reintroduce that tracking
         // once the asynchronous workers support cancellation on a multi-thread runtime.
     }
diff --git a/crates/shirabe/src/util/process_executor.rs b/crates/shirabe/src/util/process_executor.rs
index 4808d0be..3f300317 100644
--- a/crates/shirabe/src/util/process_executor.rs
+++ b/crates/shirabe/src/util/process_executor.rs
@@ -161,7 +161,7 @@ impl ProcessExecutor {
     /// Forwards to `execute`, returning the status code (1 on Err for compatibility) — this
     /// mirrors PHP call sites that check the `int` return of `execute()` without a surrounding
     /// `try`/`catch`, where an uncaught mock-mismatch exception would otherwise propagate.
-    // TODO(phase-d): under a strict `ProcessExecutorMock`, an incomplete expectation list now
+    // TODO(mock): under a strict `ProcessExecutorMock`, an incomplete expectation list now
     // surfaces here as a swallowed "exit code 1" instead of the old `panic!`, so a future test
     // ported through this call site could silently take a wrong branch instead of failing loudly.
     // `ProcessExecutorMockGuard::__assert_complete` still catches unconsumed expectations at
diff --git a/crates/shirabe/src/util/remote_filesystem.rs b/crates/shirabe/src/util/remote_filesystem.rs
index 28edb65c..ce24e39a 100644
--- a/crates/shirabe/src/util/remote_filesystem.rs
+++ b/crates/shirabe/src/util/remote_filesystem.rs
@@ -315,7 +315,7 @@ impl RemoteFilesystem {
         let mut error_message = String::new();
         let error_code = 0_i64;
         let mut result: Option<String> = None;
-        // TODO(phase-c): PHP captures file_get_contents warnings here via set_error_handler. Rust
+        // TODO(http): PHP captures file_get_contents warnings here via set_error_handler. Rust
         // reports I/O failures through return values rather than warnings, so error_message stays
         // empty until get_remote_contents surfaces a read reason.
         let mut http_response_header: Vec<String> = Vec::new();
@@ -617,7 +617,7 @@ impl RemoteFilesystem {
                 .into());
             }
 
-            // TODO(phase-c): PHP captures the file_put_contents warning here via set_error_handler
+            // TODO(php-semantics): PHP captures the file_put_contents warning here via set_error_handler
             // (see the get() reads above); Rust reports the failure through the return value, so
             // put_error_message stays empty until file_put_contents surfaces a write reason.
             let put_error_message = String::new();
@@ -738,7 +738,7 @@ impl RemoteFilesystem {
                     None => file_get_contents(file_url),
                 })
             } else {
-                // TODO(phase-c): wrap PHP's `file_get_contents` with stream context and error capture
+                // TODO(http): wrap PHP's `file_get_contents` with stream context and error capture
                 // for http(s) and other network schemes; depends on the unmodeled PHP stream-context
                 // layer.
                 Ok(None)
@@ -764,7 +764,7 @@ impl RemoteFilesystem {
             *response_headers = http_get_last_response_headers().unwrap_or_default();
             http_clear_last_response_headers();
         } else {
-            // TODO(phase-c): read the magic `$http_response_header` PHP variable; depends on the
+            // TODO(http): read the magic `$http_response_header` PHP variable; depends on the
             // unmodeled PHP stream layer that populates it.
             *response_headers = Vec::new();
         }
@@ -1040,7 +1040,7 @@ impl RemoteFilesystem {
                 let decoded = zlib_decode(result.as_deref().unwrap_or("").as_bytes());
 
                 result = match decoded {
-                    // TODO(phase-e): byte-string semantics — the response body travels through
+                    // TODO(bytes): byte-string semantics — the response body travels through
                     // RemoteFilesystem as a String; from_utf8_lossy can corrupt binary payloads
                     Some(d) => Some(String::from_utf8_lossy(&d).into_owned()),
                     None => {
diff --git a/crates/shirabe/src/util/sync_executor.rs b/crates/shirabe/src/util/sync_executor.rs
index 8ba45bd2..f770c6a2 100644
--- a/crates/shirabe/src/util/sync_executor.rs
+++ b/crates/shirabe/src/util/sync_executor.rs
@@ -16,7 +16,7 @@
 //! case — and for any other call site reached before `main.rs`'s runtime exists — `block_on` falls
 //! back to a disposable single-threaded runtime scoped to just that one call.
 //!
-//! TODO(phase-e): this still leaves every one of `block_on`'s call sites synchronous rather than
+//! TODO(async): this still leaves every one of `block_on`'s call sites synchronous rather than
 //! genuinely `async fn` propagated up to `Command::execute`, which remains the end goal of the
 //! async re-architecture (see the design doc). Nested `block_on` call sites (a sync fn reached
 //! from inside another `block_on`'s async block) do not run concurrently with their siblings —