docs: make branch-PR-merge the standard way changes land

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[rynfar]

Agents had to be told the integration flow every time, and the existing guidance actively pointed the other way. AGENTS.md said "Never make a PR unless the developer explicitly asks", and the review-t3-upstream skill said not to merge, push, or open a PR "unless the user explicitly requests that publishing step." Following both literally meant work got fast-forwarded straight onto pylon — which is what happened across four upstream batches today.

This makes the flow standing guidance instead of a per-task instruction.

• Adds a Landing changes section to AGENTS.md with the four steps: branch from a freshly fetched origin/pylon, verify on the branch, open a PR, merge when checks are green and approved. States plainly that pylon only ever moves by merging a PR.
• Removes the contradicting "never make a PR" rule.
• Repoints the upstream skill's Phase 6 at the same workflow, and changes its branch recipe to git switch -c <branch> origin/pylon so it no longer checks out pylon at all.
• Records that a branch checked out in a worktree is pinned there. That is how the local pylon ref silently fell 101 commits behind while batches landed from the main checkout.

Docs only — no code paths touched. vp fmt --check clean on both files.

Model: Claude Opus 5 (1M context). Harness: Claude Code.

---

^{Need help on this PR? Tag @codesmith with what you need. Autofix is disabled.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.4 KiB	11.4 KiB	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+2 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.4 KiB	11.4 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+3 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.9 KiB	5.9 KiB	+4 B (+0.1%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: c53f5b8 · PR result: 4af6aec · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.