tooling: turbo 2.11.5 writes a managed block into AGENTS.md in every agent worktree; opt out with "agentGuidance": false in turbo.json

[objectstack-fleet]

Filing-gate class: ① a defect with a named site and a measured reproduction. It is a regression from today's #21024 landing.
Routing: the maintainer direct-dispatch channel (session_018gA1pE6eJtwHhqx72G8U9X; 「相关卡片你使用项目经理技能派发处理」). It is fallout of #21024, which that ruling authorized. Routed to domain:devx / area:devpath; triage grades the priority.
Acting reader: the dispatching seat's os-dev, for one line in the root turbo.json.
Dedup: I listed objectstack's issues over REST (open, plus the most recently updated closed) and grepped them for agentGuidance, turborepo-agent-rules and turbo 2.11. 0 hits. There is no card for this.

Measured

• When it started: chore(deps)(deps-dev): bump the development-dependencies group across 1 directory with 16 updates #21024 landed turbo 2.11.5 on main at 2026-10-01T08:59Z. It had been 2.10.10. The lockfile now holds turbo@2.11.5.
• What turbo does: turbo 2.11's root option agentGuidance defaults to true. Its bundled docs/reference/configuration.mdx says: "When an AI coding agent is detected, turbo maintains a managed block in the repository-root AGENTS.md… refreshed before repository-scoped commands."
• Observed at 09:5xZ: in the worktree of the in-flight deps: take the 2026-10 production-dependency group without the better-auth family (replaces Dependabot #21029) #21094 dev, git diff -- AGENTS.md shows an 11-line uncommitted append, <!-- BEGIN:turborepo-agent-rules --> … <!-- END:turborepo-agent-rules -->. The dev never edited AGENTS.md.
• Why it matters:
  • The block tells agents to "keep the block committed with your work".
  • AGENTS.md is a governed surface. Any dev that obeys turns its PR into a human-approval PR, and the queue guard holds it there.
  • Every seat's dev hits this on its first turbo call.
• Reach at filing: none of objectstack's 11 open PRs touches AGENTS.md yet. objectui is unaffected (turbo@2.10.9).

What to do

1. Add "agentGuidance": false to the root turbo.json. That is the opt-out the bundled docs name, and it is a root-only option.
2. Acceptance: a turbo run under an agent leaves AGENTS.md unchanged. Show git diff --exit-code -- AGENTS.md after a repository-scoped turbo command, with a positive control first: the same command without the opt-out does write the block.
3. Per the docs, the opt-out does not remove a block already written. Worktrees that already carry it restore with git restore --source=HEAD --staged --worktree AGENTS.md. ⛔ Never commit the block.
4. Changeset: turbo.json publishes nothing, so skip-changeset.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 3
Session: session_018gA1pE6eJtwHhqx72G8U9X
Account: os-bill (the seat's linked user as GET /user answers it; the card's assignee from this act)
Branch: claude/issue-21146-turbo-agent-guidance
Worktree: objectstack-issue-21146
Domain: domain:devx
Seat: domain:devx#3 (the maintainer's direct-dispatch session; it holds no seat post: objectstack devx seats 1 and 2 are #6023 and #20163)
Provenance:

• Who: the maintainer.
• Verbatim: 「相关卡片你使用项目经理技能派发处理」. This card is fallout of the chore(deps)(deps-dev): bump the development-dependencies group across 1 directory with 16 updates #21024 landing, which that instruction covers.
• Where: session session_018gA1pE6eJtwHhqx72G8U9X, 2026-10-01.
  File surface:
• The root turbo.json, adding "agentGuidance": false and nothing else.
• ⛔ AGENTS.md is not on this surface. If turbo writes the block into the worktree, restore it before every commit.
• No changeset; the PR carries skip-changeset.
• Stop on a breach and explain it in the report.
  Container & model: S (one config key plus a positive-controlled measurement), mode:subagent, model: sonnet. dispatch-gates --tier: no path-derived mandate.
  Clause-②: no
  Thread-read: none
  Serial constraints cleared:
• Read on origin/main after chore(deps)(deps-dev): bump the development-dependencies group across 1 directory with 16 updates #21024 landed.
• deps: take the 2026-10 production-dependency group without the better-auth family (replaces Dependabot #21029) #21094 is in flight in area:devpath, but its surface (manifests, pnpm-lock.yaml, packages/drivers/driver-turso/src/**, one changeset) is disjoint from turbo.json, so the area rule allows it.
• No open PR touches turbo.json or AGENTS.md.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 21146,
"status": "done",
"branch": "claude/issue-21146-turbo-agent-guidance",
"pr": "#21151",
"session": "session_018gA1pE6eJtwHhqx72G8U9X",
"premise_still_valid": true,
"summary": "Added the root-only opt-out agentGuidance=false to the root turbo.json (1 file, +1 line, commit 3e3b4c9); no other file changed and AGENTS.md was never staged or committed. H1 confirmed with a positive control: on main's unmodified turbo.json (sha1 508545bda602aa2c5a7f336cf29622d0804cf030) turbo 2.11.5 turbo ls exit 0 then git diff --exit-code -- AGENTS.md exit 1 (11-line BEGIN/END turborepo-agent-rules block appended; restored then re-added on a second turbo ls); with the opt-out the same turbo ls and turbo run build --dry=json --filter=@objectstack/types both exit 0 and git diff --exit-code -- AGENTS.md exits 0 (AGENTS.md sha1 99e45344e3582f8b5e9c9e9987fc3c8375c1999d unchanged). H2: no gate or test pins turbo.json's top-level key set (readers touch tasks, globalDependencies and per-task inputs only); nothing loosened. H3 confirmed: the Check Changeset job counts changesets the PR adds and has no path exemption, only the skip-changeset label, which the PR carries after read-back. Draft PR #21151 opened, assigned os-bill, labels size/xs + skip-changeset; the PR stays draft for the PM seat.",
"tests": "No package is touched, so no build or package test was owed. Gates at HEAD 3e3b4c9 (tree identical to HEAD, git diff HEAD --quiet exit 0), every exit code captured before any pipe. Derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (9 commands, derivation identical before and after the commit, and identical to the dispatch's explicit-path spelling --commands turbo.json): node scripts/check-closing-keyword-parity.mjs :: exit 0; node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0; node scripts/check-comment-mask-corpus.mjs :: exit 0; pnpm check:driver-memory-census :: exit 0; pnpm check:gitlink-declared :: exit 0; pnpm check:nul-bytes :: exit 0; pnpm check:refd-timer-probe :: exit 0; pnpm check:turbo-task-graph :: exit 0; pnpm check:watch-hint-literal :: exit 0. --ran reconciliation with exit codes recorded: 9 derived, 9 run, 0 NOT-MEASURED, 0 UNRUN. turbo.json readers run beyond the derivation (H2): node scripts/check-ci-filter-parity.mjs --self-test :: exit 0; node scripts/check-ci-filter-parity.mjs :: exit 0; node scripts/partition-test-shards.mjs --self-test :: exit 0; pnpm check:cross-package-test-inputs :: exit 0 (turbo.json hashes every declared glob); pnpm check:examples-live-imports :: exit 0; pnpm check:type-check-coverage :: exit 0; node scripts/check-dev-prereqs.mjs --self-test :: exit 0. NOT MEASURED: live pnpm check:dev-prereqs (exit 1 = PREREQUISITE NOT MET, workspace not built, 67 of 67 packages without dist/; it reads only globalDependencies via build-input-hash.mjs, which this diff does not move). Not run, CI-owned: repo-wide pnpm lint and the rest of the check farm; select-gate-families.sh classifies turbo.json as root config, so CI runs every gate family on this PR. No ablation or reverse verification was needed: the positive control (no opt-out writes the block) and the treatment (opt-out leaves AGENTS.md unchanged) are the two-sided proof, both observed on the 2.11.5 binary.",
"mcp_calls": "0 — no MCP tool of any kind was called",
"api_writes": "5 writes: git push x2 (empty-branch write probe, then commit 3e3b4c9; git push is not a REST write); relay dispatch x3, each POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot]: (1) pr_create (POST /pulls, draft, read-back 4254 bytes sent = 4254 stored) -> #21151; (2) one label-write call, labels_add skip-changeset (POST /issues/21151/labels) + assign os-bill (POST /issues/21151/assignees), read-back matched; (3) this os-dev-report comment (POST /issues/21146/comments). Reads (not counted): gh api GET of the card, its comments and the PR.",
"open_questions": [],
"out_of_scope_findings": [
"carrier: none (承接者:无) · noted, not filed · objectui is unaffected today (turbo 2.10.9 per the card), but the same default will apply when it moves to turbo 2.11 or later and the opt-out key is root-only per repository; this PR's Acceptance notes do not carry it, the seat may add it",
"carrier: none (承接者:无) · noted, not filed · worktrees opened before this lands (for example the #21094 dev's) may already hold the uncommitted block; per turbo's docs the opt-out does not remove an existing block, restore with git restore --source=HEAD --staged --worktree AGENTS.md and never commit it (already in the PR Acceptance notes)"
],
"gates": {
"derived_command_count": 9,
"derived_all_exit_zero": true,
"ran_reconciliation": "9 derived, 9 run, 0 NOT-MEASURED, 0 UNRUN",
"extra_readers_all_exit_zero": [
"check-ci-filter-parity (+ self-test)",
"partition-test-shards --self-test",
"check:cross-package-test-inputs",
"check:examples-live-imports",
"check:type-check-coverage",
"check-dev-prereqs --self-test"
],
"not_measured": [
"live pnpm check:dev-prereqs: PREREQUISITE NOT MET, workspace not built; no package is touched"
],
"ci_owned_not_run": [
"pnpm lint (repo-wide)",
"the remaining check:* farm"
],
"head": "3e3b4c915",
"ci_state_at_report": "not awaited (draft PR just opened); convergence is the PM's read"
},
"line_budget": {
"applicable": false,
"reason": "no skills/** or other line-ratcheted surface touched",
"diff": "turbo.json +1/-0, size/xs"
},
"deviations": [
"Positive control ran in the issue worktree on main's unmodified turbo.json (sha1 508545bda602aa2c5a7f336cf29622d0804cf030, byte-identical to origin/main) before the edit, not on a separate scratch copy; the block it wrote into the worktree AGENTS.md was restored with git restore --source=HEAD --staged --worktree AGENTS.md before the commit, and git diff --cached --name-only listed turbo.json only.",
"The PR's skip-changeset label and the os-bill assignee mirror went out in ONE label-write call (one relay dispatch, two actions) instead of two calls; both landed and the read-back matched; the write budget is not exceeded.",
"The dispatch spelled the gate derivation with the path --commands turbo.json; the definition's no-path form was also run and the two derive the identical 9-command set."
],
"files_changed": [
"turbo.json"
]
}

[objectstack-fleet]

Review: ACCEPT, PR #21151 (head 3e3b4c915f)

Reviewed 2026-10-01T10:10Z by the PM seat (session_018gA1pE6eJtwHhqx72G8U9X) against GitHub, not against the report.

• Shape: the PR is a draft against main. Its body opens Fixes #21146 / Clause-②: no, with no other closing keyword. The assignee is os-bill, and the labels include skip-changeset.
• Scope: one file, turbo.json, +1/−0: "agentGuidance": false at the root, beside globalPassThroughEnv. AGENTS.md is not in the diff. check-governed-merges --pr 21151: NOT governed.
• Evidence I spot-checked: the two-sided measurement on the turbo 2.11.5 binary.
  • Without the opt-out, turbo ls appends the 11-line turborepo-agent-rules block, and git diff --exit-code -- AGENTS.md exits 1.
  • With it, turbo ls and turbo run build --dry=json leave AGENTS.md unchanged, and the same check exits 0.
  • The 9 derived gates exit 0, with --ran reconciled.
• CI at review: 12 success, 11 skipped on the path filter, 2 running (Lint & Repo Gates, Type Check · workspace). The seat lands the PR once every check is green or an expected skip.
• Out of scope, noted, not filed: objectui is on turbo 2.10.9 today, so the same default will reach it when it bumps to 2.11 or later. That bump's PR should carry the same root opt-out. There is no reach today, so there is no card.

---

Generated by Claude Code