[Docs] Document fork-to-upstream contribution workflow

[clintebbesen]

Purpose

Add a durable contributor guide to clintebbesen/t3code so agents can work on real T3Code defects through the fork and contribute fixes upstream without losing the rationale when a terminal session ends.

This is documentation for the fork’s operating process, not a request to implement either reliability fix. The current canonical reliability references are upstream #6517 and upstream #5389; future agents must repeat the duplicate/fix check before opening another issue or branch.

Required deliverable

Add docs/upstream-development.md (or the repository’s established contributor-doc location if current main has a better owner) through a short-lived documentation branch based on current upstream main.

The guide must explain, with copyable commands where useful:

1. pingdotgg/t3code is the upstream remote and clintebbesen/t3code is the working fork.
2. The fork’s main tracks upstream and is not a permanent patch branch.
3. Each fix starts from a fresh short-lived branch based on current upstream main.
4. Before coding, search upstream issues, pull requests, current source, and recent releases for an existing fix or in-flight implementation.
5. If an upstream PR already covers the defect, fetch/test that branch in the fork and contribute only the remaining gap; do not recreate the same fix.
6. Reproduce the defect with a regression test, identify and extend the existing owner/layer, run project checks, and record the exact commit and evidence.
7. Push only the feature branch to the fork and open a PR from the fork to pingdotgg/t3code:main; never merge automatically.
8. While a PR is open, synchronize with current upstream through the normal review process without broadening the PR’s purpose.
9. After upstream merges and publishes an official release, update the local installation to that official release and retire the fork build; do not accumulate permanent overlay patches.
10. Keep credentials in approved authentication/configuration mechanisms. Never put tokens, keys, passwords, or .env contents in issues, commits, documentation, or transcripts.
11. State the boundary between isolated test environments and the live T3Code service/database; no agent should restart, deploy, or mutate live state without explicit authorization.
12. Link the current reliability coordination issues and explain that the two defects are separately scoped.

Acceptance criteria

• The guide exists in the fork at the chosen documented path and is linked from the repository’s contributor documentation/index if one exists.
• It is self-contained enough for an agent with no access to this conversation to follow the fork → branch → test → PR → upstream release lifecycle.
• It explicitly requires a duplicate/fix search before new issue creation or implementation.
• It contains no credentials or machine-specific secrets.
• The documentation change is submitted as a focused PR to upstream; no merge or deployment is performed as part of this task.

Verification

Read the final Markdown from the committed candidate, verify every required workflow step is present, run the repository’s documentation/lint checks if defined, and record the exact branch/commit and checks. Use the normal fork workflow; do not edit the old investigation checkout as a substitute.

Fork coordination links

• Issue #1 — ProviderCommandReactor lockout coordination
• Issue #2 — Codex JSONL framing coordination
• Issue #3 — Fork-to-upstream workflow documentation

[clintebbesen]

Documentation PR opened upstream: https://github.com/pingdotgg/t3code/pull/7069\n\nIt targets pingdotgg/t3code:main from clintebbesen:docs/upstream-development-workflow, links the guide from the contributor docs, and keeps the provider and Codex reliability defects separately scoped. It remains unmerged.