F-089: Safe Args navigation task cache (GH #110)

TICKETS.md

@@ -120,7 +120,7 @@ Promoted from daily next-actions / historical GH. Workers pick top `todo` in ord
 |----|--------|-------|-------|
 | F-087 | done | AndroidX / SDK ceiling after AGP 9 | compile/target **37**; core **1.19.0**, activity **1.13.0**, lifecycle **2.11.0**, compose **1.11.4**, room **2.8.4**, material **1.14.0**; JVM **11**; navigationevent on activity graph; paging **2.1.2** kept. Host+CI platform 37. |
 | F-088 | done | Fleet tooling phase 2 (F-084 follow-ups) | Gradle `formaLayoutCheck`/`formaLayoutGenerate` + root `*All` via `tools.forma.deps.fleet.registerFormaLayout` on all packageName DSLs; opt-in `checkPackageLayoutAtConfiguration` (default false); res/viewBinding/binary skip source-dir requirement; docs/skill updated. GH **#54** generate path user-complete (Hermes may close). AST migrate / depgen still deferred. |
-| F-089 | todo | Navigation task cache broken | GH **#110** — fix navigation/safe-args related task cache so config/build cache is correct; reproduce from issue screenshots; add regression note or test if feasible; plugins+app green. |
+| F-089 | done | Navigation task cache broken | GH **#110** — upstream Safe Args **2.9.8** already `@PathSensitive(RELATIVE)` on `navigationFiles`; two-location build-cache hit verified on sample `navigationRes`; regression note in `docs/CONFIGURATION-PERFORMANCE.md`. |
 | F-090 | todo | Exclude modules from dependency validation | GH **#97** — allow-list / opt-out for forked-in libraries (ExoPlayer-class cases) without weakening default matrix. One global configuration path (not per-call-site escape hatch spam). Docs + sample or unit coverage. |
 | F-091 | todo | BuildFeatures under Forma | GH **#88** — map AGP `BuildFeatures` into Forma (default off where safe); single configuration path aligned with type=rule + project-global defaults; document in CALL-SITE / PROJECT-CONFIGURATION. Do not reintroduce fat call-site plugin shopping. |
 | F-092 | todo | versionCode / versionName on binary (and app) | GH **#82** — move version identity off global-only `FormaConfiguration`; set on `androidBinary` / `androidApp` as call-site attrs (Gradle limits acknowledged). Sample uses new API; docs. |

docs/CONFIGURATION-PERFORMANCE.md

@@ -106,10 +106,59 @@ root buildscript evaluation and read during project configuration of the same
 build — which is the supported layout. Do not mutate the store from task
 actions.
 
+### Navigation Safe Args task cache (F-089 / GH #110)
+
+**Symptom (historical):** Develocity “different project locations” experiment
+showed `:…:generateSafeArgs*` (`ArgumentsGenerationTask`) as cacheable but
+**not** taken `FROM-CACHE` across checkouts. Build Scan diff:
+`navigationFiles` with **Absolute path** normalization (plus empty dirs /
+non-normalized line endings on very old plugin lines).
+
+**Root cause:** Older Navigation Safe Args Gradle plugin recorded
+`navigationFiles` with absolute-path sensitivity, so the build-cache key
+embedded the checkout path.
+
+**Resolution on current `v2` toolchain (no Forma fork of the plugin):**
+
+| Pin | Notes |
+|-----|--------|
+| `androidx.navigation:navigation-safe-args-gradle-plugin` **2.9.8** (sample) | Task is `@CacheableTask`; `getNavigationFiles()` is `@PathSensitive(PathSensitivity.RELATIVE)` + `@Incremental` (verified on 2.7.4+ jars in cache; keep **≥ 2.7.x** / current stable with AGP 9) |
+| Path B `navigationRes` | Type-owned `androidx.navigation.safeargs.kotlin` — see [`TARGET-PLUGINS.md`](TARGET-PLUGINS.md) |
+| AGP library `verify*Resources` | Still disabled for pure res/safe-args graphs (unrelated packaging strictness) |
+
+**Host regression (2026-07-22):** two detached worktrees, shared local build
+cache directory, `:core-navigation-res:clean generateSafeArgsDebug` —
+
+- location A stores cache key `328f4fa9dc90662111aac019e754a4da`
+- location B loads the **same** key → `FROM-CACHE`
+- same-tree `clean` + task → `FROM-CACHE`; warm run → `UP-TO-DATE`
+- `--configuration-cache` configures and runs the task successfully (CC entry
+  store/reuse can still miss for unrelated composite/settings inputs; that is
+  **not** the GH #110 absolute-`navigationFiles` bug)
+
+**Do not** reintroduce call-site `.withPlugin` / free-form plugin lists to
+“fix” cache — pin Safe Args + type-owned apply only.
+
+**Quick re-check:**
+
+```bash
+source scripts/env-mac.sh
+cd application
+./gradlew :core-navigation-res:clean :core-navigation-res:generateSafeArgsDebug \
+  --build-cache --no-configuration-cache --info
+# expect: Build cache key … generateSafeArgsDebug … and FROM-CACHE or STORE once
+```
+
+Optional two-location recipe (same commit, shared `--init-script` local cache
+dir, distinct `--project-cache-dir` / worktrees): both must share one cache key
+for `generateSafeArgsDebug`.
+
 ## Related
 
 - GH #106 Optimize configuration time
 - GH #42 Build performance impact
+- GH #110 Navigation task cache broken → **F-089**
 - `docs/ARCHITECTURE.md` — module map
 - `docs/DEPS-CATALOG.md` — pure generators
-- Ticket **F-017**
+- `docs/TARGET-PLUGINS.md` — `navigationRes` / safe-args
+- Ticket **F-017**, **F-089**

docs/PROGRESS.md

@@ -2,6 +2,30 @@
 
 Newest entries first.
 
+## 2026-07-22 — F-089: Navigation Safe Args task cache (GH #110)
+
+- **Ticket:** F-089 → `done`
+- **Branch:** `forma/F-089-nav-task-cache` (from origin/v2 @ 246b6f4)
+- **Skills/modes:** Hermes investigation + docs (no product DSL change required)
+- **Issue read:** GH #110 screenshots (Develocity exp3 different project locations) —
+  `ArgumentsGenerationTask.navigationFiles` absolute-path normalization broke
+  cross-checkout build-cache reuse on old Safe Args / AGP 7.x era.
+- **Bytecode check:** `navigation-safe-args-gradle-plugin` **2.7.4 / 2.7.7 / 2.8.9 / 2.9.8**
+  all annotate `getNavigationFiles()` with `@PathSensitive(RELATIVE)` + `@CacheableTask`.
+  Sample already pins **2.9.8** + Path B `navigationRes`.
+- **Reproduce/verify (real host, `source scripts/env-mac.sh`):**
+  - Two git worktrees + shared local build-cache dir:
+    `:core-navigation-res:generateSafeArgsDebug` key
+    `328f4fa9dc90662111aac019e754a4da` → second location **FROM-CACHE**
+  - Main tree: clean → **FROM-CACHE**; warm → **UP-TO-DATE**
+  - `--configuration-cache` run **BUILD SUCCESSFUL** (task executes; CC reuse may
+    still miss on composite inputs — out of #110 absolute-path scope)
+- **Code changes:** none in plugins (fix is dependency-era + pin). Docs only:
+  `docs/CONFIGURATION-PERFORMANCE.md` Safe Args cache section; board/PROGRESS.
+- **GH #110:** close when this PR merges (comment with verify summary).
+- **Blockers:** none
+- **Next:** F-090 Exclude modules from dependency validation (GH #97)
+
 ## 2026-07-21 — F-088: Fleet tooling phase 2
 
 - **Ticket:** F-088 → `done`

docs/TARGET-PLUGINS.md

@@ -192,6 +192,12 @@ navigationRes(
 
 No `.withPlugin`, no `pluginConfig = pluginConfig(binding)`.
 
+**Build cache (F-089 / GH #110):** keep
+`navigation-safe-args-gradle-plugin` on a line where
+`ArgumentsGenerationTask.navigationFiles` is `@PathSensitive(RELATIVE)`
+(sample **2.9.8**). See [`CONFIGURATION-PERFORMANCE.md`](CONFIGURATION-PERFORMANCE.md)
+§ Navigation Safe Args task cache — do not paper over with call-site plugin APIs.
+
 ---
 
 ## 5. Plugin config = rule attributes (uniform, optional)