docs(requirements): say what path formatting really reaches

The contract claimed that paths inside the arguments array are not
transformed, and named output paths in flags as an example. Both halves
were false: the source argument and the output flag's value have long
been formatted with the same strategy as the file field, so an entry
cannot disagree with itself about a path a consumer may read from either
place. Only a path that is the payload of some other flag, an include
search path and its kind, is carried through as the build spelled it.

The code was right and the document was not, which is the dangerous way
round for a contract that tests are written against: nothing pinned the
real behaviour, so a later change could have "fixed" the converter to
match the text and broken every consumer that resolves a source path
from the arguments. The scenario is now written down and covered by a
test that fails when the formatting is removed.

The module doc carried the same claim, contradicting a comment ten lines
into the function it describes, so it is corrected here too.

Requirements: output-path-format

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

Author: rizsotto

crates/bear/src/output/clang/path_format.rs

@@ -29,10 +29,11 @@
 //! that fails falls back to its original path (see `CommandConverter` in
 //! `converter.rs`).
 //!
-//! The `arguments` attribute carries compiler flags, some of which embed file
-//! paths. These are intentionally left untransformed: rewriting them would
-//! require a flag-aware path rewriter for every compiler, which is fragile and
-//! out of scope.
+//! The source and output paths that reappear in the `arguments` attribute go
+//! through the `file` resolver too, so an entry cannot disagree with itself
+//! about a path. Paths embedded inside other flags (`-I../include` and its
+//! kind) are left untransformed: rewriting them would require a flag-aware
+//! path rewriter for every compiler, which is fragile and out of scope.
 
 use crate::config::PathResolver;
 use std::io;

docs/requirements/output-path-format.md

@@ -23,6 +23,8 @@ Bear provides configurable path formatting for the `directory`, `file`, and
 - The `file` field path format is configurable
 - The `output` field is formatted using the same strategy as `file`; on
   formatting failure, Bear falls back to the original unformatted path
+- The source and output paths that appear in the `arguments` array are
+  formatted with the same strategy as the `file` field
 - Four formatting behaviors are supported:
   - preserve the path exactly as observed during interception, with no
     transformation applied (the default)
@@ -51,9 +53,8 @@ Bear provides configurable path formatting for the `directory`, `file`, and
 
 ## Known limitations
 
-- Paths inside the `arguments` array (include paths, output paths in
-  flags) are deliberately not transformed. Rewriting them would require
-  a compiler-flag-aware path rewriter, which is complex and error-prone.
+- Paths embedded inside other flags, such as include search paths, are
+  not transformed; they are written exactly as the build spelled them.
 
 ## Testing
 
@@ -115,6 +116,15 @@ output is written:
 > and `output` falls back to the original unformatted path
 > `obj/main.o`, with a warning.
 
+Given a build invoked from `/home/user/project` that compiles
+`src/main.c` to `obj/main.o` and passes the include path `-I../include`:
+
+> When path format for file is `absolute`,
+> then the `arguments` array carries the source as
+> `/home/user/project/src/main.c` and the output as
+> `/home/user/project/obj/main.o`,
+> and `-I../include` is carried unchanged.
+
 Given path format for directory set to `relative`:
 
 > Then the `directory` field resolves to `.` (relative to itself),

tests/integration/tests/cases/semantic.rs

@@ -1437,6 +1437,82 @@ format:
     Ok(())
 }
 
+// Requirements: output-path-format
+//
+// The configured `file` strategy reaches the source and the output path where
+// they reappear in `arguments`, so an entry cannot disagree with itself about
+// a path a consumer reads from either place. A path that is the payload of
+// some other flag (`-I../include`) is not individually addressable and is
+// carried through exactly as the build spelled it.
+#[test]
+fn configured_file_format_reaches_the_argument_paths_but_not_flag_payloads() -> Result<()> {
+    // arrange
+    let env = TestEnvironment::new("argument_path_format")?;
+    let temp_dir = env.test_dir().to_str().unwrap();
+
+    let event = json!({
+        "executable": "gcc",
+        "arguments": ["gcc", "-c", "-I../include", "src/main.c", "-o", "obj/main.o"],
+        "working_dir": temp_dir,
+        "environment": {}
+    });
+
+    let config = r#"
+schema: "4.2"
+
+format:
+  paths:
+    directory: absolute
+    file: absolute
+  entries:
+    use_array_format: true
+    include_output_field: true
+"#;
+    env.create_source_files(&[
+        ("events.json", &event.to_string()),
+        ("src/main.c", "int main() { return 0; }"),
+    ])?;
+    let config_path = env.test_dir().join("config.yaml");
+    std::fs::write(&config_path, config)?;
+
+    // act
+    env.run_bear_success(&[
+        "--config",
+        config_path.to_str().unwrap(),
+        "semantic",
+        "--input",
+        "events.json",
+        "--output",
+        "compile_commands.json",
+    ])?;
+
+    // assert
+    let sut = env.load_compilation_database("compile_commands.json")?;
+    sut.assert_count(1)?;
+
+    // Spell the expectations the way the code does, with `Path::join` and never
+    // a literal separator, so the assertion holds on Windows too.
+    let source = env.test_dir().join("src").join("main.c");
+    let object = env.test_dir().join("obj").join("main.o");
+
+    sut.assert_contains(
+        &CompilationEntryMatcher::new()
+            .file(source.to_str().unwrap())
+            .directory(temp_dir)
+            .output(object.to_str().unwrap())
+            .arguments(vec![
+                "gcc".to_string(),
+                "-c".to_string(),
+                "-I../include".to_string(),
+                source.to_str().unwrap().to_string(),
+                "-o".to_string(),
+                object.to_str().unwrap().to_string(),
+            ]),
+    )?;
+
+    Ok(())
+}
+
 // Requirements: output-header-entries
 //
 // A synthesized header entry clones the donor's arguments with the output