huskies: merge 620_refactor_enforce_test_fixture_discipline_in_service_modules

docs/architecture/service-modules.md

@@ -86,6 +86,30 @@ HTTP handlers map service errors to **specific** HTTP status codes:
 
 ## 4. Test Pattern
 
+### Chosen default pattern: fixture helpers in `io::test_helpers`
+
+All filesystem setup for tests lives in a `#[cfg(test)] pub mod test_helpers`
+block inside `io.rs`. Test blocks in `mod.rs` and topic files call these
+helpers instead of importing `std::fs` directly.
+
+**Grep-enforceable check for test code:** The following must NOT appear inside
+`#[cfg(test)]` blocks in any `service/<domain>/` file **other than `io.rs`**:
+
+- `std::fs::` (any item)
+- `tokio::fs`
+- `std::process::` (any item)
+- `Command::new`
+
+Run to verify:
+
+```sh
+grep -rn --include='*.rs' \
+  'std::fs::\|tokio::fs\|std::process::\|Command::new' \
+  server/src/service/ | grep -v '/io\.rs'
+```
+
+This must return zero matches (including lines inside `#[cfg(test)]` blocks).
+
 ### Pure topic files (`<topic>.rs`)
 
 ```rust
@@ -104,6 +128,17 @@ mod tests {
 ### `io.rs`
 
 ```rust
+/// Fixture helpers — the ONLY place allowed to call std::fs in tests.
+#[cfg(test)]
+pub mod test_helpers {
+    use tempfile::TempDir;
+
+    pub fn make_work_dirs(tmp: &TempDir) { ... }
+    pub fn make_stage_dirs(tmp: &TempDir) { ... }
+    pub fn make_project_toml(tmp: &TempDir, content: &str) { ... }
+    pub fn write_story_file(tmp: &TempDir, relative_path: &str, content: &str) { ... }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -122,6 +157,7 @@ mod tests {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use io::test_helpers::*;  // ← fixture helpers; never import std::fs here
 
     // Integration tests compose io + pure layers end-to-end.
     // May use tempdirs. Keep the count small — they are integration-level.