docs(agents): shared-identity caution + session-URL PR footer form (#6567)

[os-project-manager]

Fixes #6567

Documentation/process only. Two focused additions, in the two places the triage ruling named, and nothing else.

What landed

1. AGENTS.md — "Multi-agent working discipline", right after the shared-identity claim paragraph.

Two new paragraphs:

• "State on your PR that you did not set belongs to another actor — ask, never correct it." Under one shared GitHub identity every other participant's write arrives unsigned: the PM's ready-flip and auto-merge arming, a bot re-labelling, the platform rewriting the body. The update_pull_request 每次编辑都剥掉尾部 _Generated by [Claude Code]_ footer —— 只剥裸 URL 那种，带 session URL 的存活；它被误读成「机器在改我的 PR」，已造成一次 auto-merge 静默销毁 #6567 incident is cited as the worked example, including the part that makes it expensive — flipping a ready PR back to draft drops auto-merge and merge-queue membership at once (cross-referenced to §7's third re-arm situation), and pull_request_read reports neither, so the agent could not see what it had destroyed.
• "Write the attribution footer in its session-URL form" — the mechanism, with the two footer spellings side by side, plus the honest blank: which layer performs the rewrite is unknown and the guidance does not depend on the answer, so nobody should spend a session establishing it.

The placement is deliberate. The paragraph immediately above already ends with "misreading shared-identity state is also how a maintainer's manual ready-flip got reverted by an agent that assumed its own write had failed" — a one-clause version of the same class. The new paragraph generalises it and adds the second incident rather than restating it, so neither sentence is left redundant.

2. .claude/agents/os-dev.md — three touches.

• Rule 2 (the shared-identity rule) gains the same caution as a sub-bullet, ending with what the incident specifically needed: the dev hands over a draft, and the PM flipping it ready and arming auto-merge is the normal next step of the process, not something acting on the PR. The template never stated this before, which is part of why the flip read as machine noise.
• The "Definition of done" draft-PR bullet gains a one-clause pointer to the footer form.
• The closing GitHub-body-sanitizer paragraph — already the file's home for "the stored body is rewritten at rest" — gains the footer guidance, both spellings, and the same explicit "which layer is unknown, do not chase it".

Premise re-verification (before writing any of it)

The issue body is a lead, so the load-bearing claim was re-checked against the live API rather than taken on trust:

claim	how it was checked	result
the session-URL footer form survives on PR #6556	pull_request_read get on #6556 — the stored body, not the rendered page	its last line is _Generated by [Claude Code](https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3)_. Holds.
#6556's body was in fact edited after creation	the stored body itself says so: it discusses what "本 PR 初版正文" rendered as, i.e. a later revision describing an earlier one	holds — the surviving footer survived edits, not merely creation
comments are a different path	the two comments on #6567 (triage + claim) both end in the bare https://claude.ai/code form and are intact	holds — comments are unaffected, so the guidance is correctly scoped to PR bodies

The strip itself was not re-run as a fresh experiment: reproducing it means deliberately writing a footer form this PR is telling everyone not to write. The filer reproduced it twice on #6556 and that record is what the guidance cites. What this PR does verify live is the half it actually recommends — this body is written in the session-URL form, and it is expected to survive every update_pull_request edit made while the PR is open.

⛔ Deliberately not established: which layer strips the footer (platform sanitizer / MCP tool layer / a workflow's body post-processing). The triage ruling says the fix does not depend on the answer, so no cycles were spent on it, and both new passages record the cell as blank instead of guessing.

Deliberately omitted

.claude/skills/pm-dispatch/SKILL.md was not touched. It is a known contention surface — #5925 holds pm:dispatched on a card whose deliverable edits that file. Nothing in this change needed it: SKILL.md carries no footer requirement (the footer comes from the harness, not the repo template), and the ready-flip ordering note it owns is already cross-referenced from AGENTS.md §7 rather than duplicated.

Gates

Run after git commit, enumerated from .github/workflows/lint.yml rather than from memory. Every gate in the ESLint job, plus the .claude-reading gates from the TypeScript Type Check job:

gate	result
check:nul-bytes	OK (scanned 6235 tracked text file(s) ... no raw ASCII control bytes)
check:doc-authoring	365 files clean
check:role-word	OK (44 baselined file(s), no new occurrences)
check:docs-audit-scope, check:quick-reference-counts, check:adr-anchors, check:org-identifier, check:authz-resolver, check:service-providers, check:route-envelope, check:error-code-casing, check:wildcard-fallthrough, check:meta-type-normalized, check:init-service-contract, check:durability-log-level, check:startup-registry-verdict, check:objectui-changeset, check:release-notes, check:release-body, check:node-version, check:workflow-status-functions, check:slot-lookup, check:query-options-erasure, check:verify-stand-in	all EXIT=0
check:skill-frame-sync	4 copies of the decision frame are structurally isomorphic across 3 files — the frame lives in os-dev.md too, so this is the gate that would have caught a careless edit there
check:skill-frame-freshness, check:skill-compatibility, check:empty-changeset, check:published-files	EXIT=0
pnpm lint (ESLint, eslint . --no-inline-config)	LINT_EXIT=0
grep -naP control-byte self-scan of both edited files	no hits

No test suite applies: the change adds no runtime code and no test surface. pnpm typecheck has no input here for the same reason — neither AGENTS.md nor .claude/agents/os-dev.md is in any TS program. CI's full TypeScript Type Check job still runs and is being watched.

Changeset

None, and skip-changeset applied. This PR changes only AGENTS.md and a .claude/ agent definition — the agent operating manual. It publishes no package, changes no runtime behaviour and reaches no consumer, so there is nothing for a changeset to describe in a release.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 12:52pm