From 749e62ca13c35947db33c43c45fe674c43d79e32 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 18 Aug 2026 12:56:03 +0000
Subject: [PATCH] build(turbo): declare content/docs as an input to build and
 type-check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`content/docs/` lives at the repo root, outside the `apps/docs` package, but
both `build` and `type-check` consume it — `source.config.ts` points fumadocs
at `../../content/docs`. With no `inputs` declared, turbo's default hash covers
only the package directory, so a content-only change did not move the hash and
both tasks replayed a cached green. The cache is shared across worktrees in a
multi-agent container, so the replayed logs could come from a sibling agent's
tree, which makes the false green look like a real run.

Declare the dependency with the root-anchored `$TURBO_ROOT$` microsyntax rather
than a hand-counted `../../`. Both resolve identically on turbo 2.9.14 (measured:
same 450-entry input list, same hashes), but a relative glob encodes the
package's depth and silently matches nothing if the package moves — and a wrong
inputs glob is not an error, it exits 0 and reverts to the stale hash.

Task-level `inputs` rather than root `globalDependencies`: globalDependencies
feeds the global hash, so it would bust every task in the repo, including `lint`,
which does not read content/docs (measured).

AGENTS.md documents how to verify the hash actually tracks content, plus the
`--force` escape hatch for anyone on a turbo older than 2.4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa
---
 AGENTS.md  | 32 ++++++++++++++++++++++++++++++++
 turbo.json |  4 +++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5b6d3e9..3286fc1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -79,3 +79,35 @@ From `apps/docs/`:
 - `npm run dev` — dev server on http://localhost:3001
 - `npm run type-check` — `fumadocs-mdx && next typegen && tsc --noEmit`
 - `npm run build` — production build
+
+## Turbo caching and content changes
+
+`content/docs/` sits at the repo root, **outside** the `apps/docs` package, but both
+`build` and `type-check` genuinely consume it (`source.config.ts` points fumadocs at
+`../../content/docs`). Turbo's default hash only covers the package's own directory, so
+those tasks used to replay a cached green for a content-only change — and because the
+cache is shared across worktrees in a multi-agent container, the replayed logs could come
+from a *sibling agent's* tree. `turbo.json` now names the dependency explicitly:
+
+```json
+"inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/content/docs/**"]
+```
+
+`$TURBO_ROOT$` is anchored to the repo root by turbo itself. Prefer it over a hand-counted
+`../../` — both work today, but a relative glob encodes the package's depth, and if the
+package ever moves the glob silently stops matching.
+
+**Verify the hash, don't trust the config.** A wrong `inputs` glob is not an error: turbo
+exits 0, matches nothing, and the task silently goes back to the stale hash. So when you
+change these globs, confirm the hash actually moves — edit any file under `content/docs/`,
+then revert it, and check the hash changes and comes back:
+
+```bash
+turbo run type-check --filter=@objectos/docs --dry=json | jq -r '.tasks[0].hash'
+```
+
+Belt and braces: `turbo run build --force` ignores the cache entirely. Reach for it if you
+are verifying a content change on a turbo older than 2.4 (before `$TURBO_ROOT$` existed,
+where the glob above matches nothing), or any time a `>>> FULL TURBO` on a content PR
+looks wrong. `--force` is the escape hatch, not the routine path — the hash is supposed to
+tell the truth on its own.
diff --git a/turbo.json b/turbo.json
index 3c575ff..413cd9b 100644
--- a/turbo.json
+++ b/turbo.json
@@ -4,6 +4,7 @@
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/content/docs/**"],
       "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
     },
     "dev": {
@@ -15,7 +16,8 @@
     },
     "lint": {},
     "type-check": {
-      "dependsOn": ["^build"]
+      "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/content/docs/**"]
     },
     "clean": {
       "cache": false