From 68a50ad9abe44aa3ec212d27285ffbe9b798d349 Mon Sep 17 00:00:00 2001 From: Michael Johnston Date: Wed, 12 Aug 2026 20:54:27 -0700 Subject: [PATCH 1/4] docs(lastcode): define contribution workstreams --- .agents/skills/lastcode-pr/SKILL.md | 70 +++++++++ .agents/skills/lastcode-pr/agents/openai.yaml | 4 + .agents/skills/upstream-fix/SKILL.md | 64 ++++++++ .../skills/upstream-fix/agents/openai.yaml | 4 + docs/lastcode/README.md | 5 +- docs/lastcode/fork-conventions.md | 139 ++++++++++++++++-- 6 files changed, 270 insertions(+), 16 deletions(-) create mode 100644 .agents/skills/lastcode-pr/SKILL.md create mode 100644 .agents/skills/lastcode-pr/agents/openai.yaml create mode 100644 .agents/skills/upstream-fix/SKILL.md create mode 100644 .agents/skills/upstream-fix/agents/openai.yaml diff --git a/.agents/skills/lastcode-pr/SKILL.md b/.agents/skills/lastcode-pr/SKILL.md new file mode 100644 index 000000000000..0627e505dc17 --- /dev/null +++ b/.agents/skills/lastcode-pr/SKILL.md @@ -0,0 +1,70 @@ +--- +name: lastcode-pr +description: Deliver a LastCode-only change through its branch, local CI, Codex review, and guarded merge workflow. Use for Markover integration, LastCode identity or branding, personal conveniences, nightly checkpointing, ad-hoc releases, and any change intentionally not proposed to pingdotgg/t3code. Use upstream-fix instead when a general improvement should also be offered upstream. +--- + +# LastCode PR + +Ship fork-only work from the canonical downstream base without contaminating the +clean upstream mirror. + +## Classify and Branch + +Read `docs/lastcode/fork-conventions.md` and the repository `AGENTS.md` first. +If the change makes sense to a T3 Code user without LastCode or Markover context +and should be proposed upstream, switch to `upstream-fix`. + +1. Ensure the worktree is clean and fetch `origin` with pruning. +2. Create `lastcode/markover/` for Markover integration or + `lastcode/` for other fork-only work from the exact + `origin/lastcode/main`. +3. Keep one concern per branch and PR. Put downstream contributor and operations + documentation under `docs/lastcode/`. +4. Never target `main` or `pingdotgg/t3code` from this workflow. + +## Implement and Validate + +1. Implement the smallest complete change, including focused regression tests + for backend or automation behavior. +2. Run the smallest relevant tests, lint, and typecheck required by `AGENTS.md`. +3. Rebase onto the latest `origin/lastcode/main` before publishing. +4. Push the branch; the pre-push hook must pass `pnpm lastcode:ci:quick` locally. +5. Open a PR targeting `lastcode/main` only when the user explicitly asks. + +An open PR targeting `lastcode/main` pauses promotion of a new nightly onto the +branch. Checkpoint automation still publishes every immutable nightly tag and +promotes the newest one after the PR queue is empty. + +## Babysit and Merge + +When the user asks to babysit or merge: + +Read `.agents/skills/_references/external-review-mechanics.md` for the repository's +current GitHub thread and review-query mechanics. + +1. Inspect comments and thread-level review state newer than the latest push. +2. Verify each bot finding against the source. Fix real defects; reply with a + concrete reason when a finding is false. Resolve only addressed threads. +3. Request `@codex review` after each fix push. Do not merge until Codex gives an + explicit clean result for the exact current head and no review thread remains + unresolved. +4. Run `pnpm lastcode:ci` from a clean branch. Its full-CI stamp must match the + exact head and fetched `origin/lastcode/main` base. +5. Use `pnpm lastcode:merge`; do not bypass the guarded merge in the GitHub UI. +6. Verify the PR is merged and `origin/lastcode/main` contains the merge result. +7. If the work is tracked by Markover, confirm the GitHub terminal state and + run the service-free command from the Markover checkout: + + ```bash + npm --silent run markover -- done --pr-status merged + ``` + +Follow the repository's bounded CI polling rule. Stay quiet when no new review +or check result exists, and stop only when the latest commit is clean or a real +external blocker requires the user. + +## Handoff + +Report the PR URL, merged commit or current head, focused and full validation, +Codex review result, unresolved-thread count, and Markover state when applicable. +If no PR was requested, report the local branch and commit without publishing it. diff --git a/.agents/skills/lastcode-pr/agents/openai.yaml b/.agents/skills/lastcode-pr/agents/openai.yaml new file mode 100644 index 000000000000..4f5472fce5d8 --- /dev/null +++ b/.agents/skills/lastcode-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "LastCode PR" + short_description: "Ship a fork-only change through LastCode local CI" + default_prompt: "Use $lastcode-pr to deliver this fork-only change through the LastCode PR workflow." diff --git a/.agents/skills/upstream-fix/SKILL.md b/.agents/skills/upstream-fix/SKILL.md new file mode 100644 index 000000000000..800483779b7e --- /dev/null +++ b/.agents/skills/upstream-fix/SKILL.md @@ -0,0 +1,64 @@ +--- +name: upstream-fix +description: Prepare and deliver a general T3 Code fix or improvement that should be proposed to pingdotgg/t3code while LastCode retains an independent copy. Use for upstream-worthy bugs and features, paired upstream and LastCode PRs, refreshing the clean contribution base, or porting an upstream candidate into lastcode/main. Do not use for Markover integration, LastCode branding, personal workflow assumptions, or release automation; use lastcode-pr for those. +--- + +# Upstream Fix + +Deliver one logical improvement through two independent branches: an +upstream-pure contribution and a LastCode port. Keep their bases, reviews, CI, +and merge decisions separate. + +## Classify the Change + +Use this workflow only when the behavior makes sense to a T3 Code user with no +LastCode or Markover context. Route fork identity, Markover integration, personal +conveniences, nightly automation, and local release machinery to `lastcode-pr`. + +Read `docs/lastcode/fork-conventions.md` before changing branches. Follow the +repository `AGENTS.md` on both branches. + +## Prepare the Upstream Delivery + +1. Ensure the worktree is clean. Fetch `upstream` and `origin` with pruning. +2. Confirm `upstream` is `pingdotgg/t3code` and `origin` is the writable fork. +3. Fast-forward the fork mirror with `git push origin upstream/main:main`. If it + is not a fast-forward, stop and inspect; never merge or force downstream + history into `main`. +4. Create `fix/` or `feat/` from the exact fetched + `upstream/main`, not from `lastcode/main`. +5. Implement one upstream concern. Exclude LastCode branding, Markover details, + downstream automation, and `docs/lastcode` changes. +6. Run the smallest relevant tests and checks required by `AGENTS.md`. +7. Fetch and rebase onto the latest `upstream/main` immediately before opening + the PR. Push to `origin` and target `pingdotgg/t3code:main`. +8. Follow upstream CI and review conventions. Verify review findings against the + source, address real issues, and explain false positives. + +Do not open a PR unless the user explicitly asks. + +## Prepare the LastCode Delivery + +1. Fetch `origin` again and create `port/upstream/` from the exact + `origin/lastcode/main`. +2. Cherry-pick the upstream change when clean; otherwise reimplement the same + behavior against LastCode without dragging in unrelated upstream history. +3. Preserve any LastCode-specific adaptation only on this branch. +4. Run focused validation. A push invokes quick local CI. +5. When asked to open a PR, target `lastobelus/lastCode:lastcode/main` and link + the upstream PR in both descriptions. +6. Before merge, require a current-head clean Codex review, zero unresolved + review threads, and full local CI for the exact head and current base. Merge + through `pnpm lastcode:merge`. + +The LastCode PR does not wait for upstream acceptance. The upstream PR does not +depend on LastCode. When upstream later lands the change, let the nightly rebase +reconcile the duplicate patch and record any recurring resolution through the +existing checkpoint workflow. + +## Handoff + +Report both branch names and PR URLs, their bases and current heads, validation +performed for each, review status, and whether either delivery remains local. +Call out that an open LastCode PR pauses branch promotion while immutable nightly +checkpoint tags continue. diff --git a/.agents/skills/upstream-fix/agents/openai.yaml b/.agents/skills/upstream-fix/agents/openai.yaml new file mode 100644 index 000000000000..bb5e2e22e9da --- /dev/null +++ b/.agents/skills/upstream-fix/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Upstream Fix" + short_description: "Ship an upstream change while retaining it in LastCode" + default_prompt: "Use $upstream-fix to prepare an upstream T3 Code change and its independent LastCode port." diff --git a/docs/lastcode/README.md b/docs/lastcode/README.md index be60bd50b4b5..ca3b042dfc63 100644 --- a/docs/lastcode/README.md +++ b/docs/lastcode/README.md @@ -11,8 +11,9 @@ be checkpointed, while only selected checkpoints need full local CI and a build. scheduling, recovery, and provenance. - [Release workflow](release.md): local CI, PR merging, ad-hoc signing, builds, and runtime isolation. -- [Fork conventions](fork-conventions.md): remotes, branch intent, upstream pull - requests, alternate forks, and evaluation tags. +- [Contribution and fork conventions](fork-conventions.md): the two workstreams, + contribution bases, paired upstream/LastCode changes, remotes, branches, and + evaluation tags. ## Command Summary diff --git a/docs/lastcode/fork-conventions.md b/docs/lastcode/fork-conventions.md index 0a4b43bfc61e..d39770310032 100644 --- a/docs/lastcode/fork-conventions.md +++ b/docs/lastcode/fork-conventions.md @@ -1,16 +1,52 @@ -# LastCode Fork Evaluation Conventions +# LastCode Contribution and Fork Conventions -This document defines how `lastCode` tracks the upstream project, the canonical -LastCode fork branch, notable forks, and candidate pull requests. +This document defines how LastCode separates fork-only work from changes offered +upstream, keeps both contribution bases current, and evaluates other forks. ## Goals -- Keep `lastCode` usable as the main working fork. +- Keep LastCode usable as the main working fork. - Keep upstream pull request branches free of LastCode-only commits. - Make it cheap to compare `pingdotgg/t3code`, `aaditagrawal/t3code`, and other forks. - Avoid losing provenance for experiments, cherry-picks, or PR evaluations. - Avoid tag collisions and remote naming drift. +## Two Workstreams + +Every change belongs to one of two workstreams before implementation begins. + +### LastCode-only work + +This stream includes Markover integration, LastCode identity and branding, +personal conveniences, local release and nightly automation, and any feature +that depends on private workflow assumptions. These changes: + +- branch from `origin/lastcode/main`; +- use `lastcode/markover/` for Markover integration or + `lastcode/` for other fork-only work; +- target `lastobelus/lastCode:lastcode/main`; and +- are not proposed to T3 Code upstream. + +### Upstream candidates retained by LastCode + +This stream includes general T3 Code fixes and improvements that should be +offered to `pingdotgg/t3code` but that LastCode wants regardless of the upstream +decision or schedule. Treat it as two independent deliveries of one logical +change: + +1. an upstream-pure PR branched from `upstream/main`; and +2. a LastCode port branched from `origin/lastcode/main`. + +The upstream branch contains no LastCode branding, Markover integration, local +release automation, or `docs/lastcode` material. Link the two PRs for provenance, +but do not make either merge depend on the other. If upstream later merges the +change, the nightly rebase reconciles the duplicate patch in the normal conflict +resolution process. + +When classification is uncertain, ask whether the change would make sense for a +T3 Code user with no LastCode or Markover context. If yes, use the paired +upstream-candidate workflow. Otherwise, keep it LastCode-only. + ## Repository Layout - Main fork checkout: `~/projects/lastCode` @@ -49,7 +85,8 @@ Use two long-lived mainline branches with distinct jobs: - `main`: upstream mirror and upstream PR base. - Local `main` should be kept aligned with `upstream/main`. - - Use `main` when creating branches for pull requests targeting `pingdotgg/t3code`. + - Create upstream PR branches from the exact fetched `upstream/main`; `main` + mirrors that base for GitHub comparisons. - Do not add LastCode-only commits directly to `main`. - `lastcode/main`: canonical LastCode branch. - This is the default branch for `lastobelus/lastCode`. @@ -61,6 +98,41 @@ Use two long-lived mainline branches with distinct jobs: This split keeps the GitHub fork useful as a project while keeping upstream contribution branches clean. +## Contribution Bases + +Never use `lastcode/main` as the base for an upstream PR. It contains the entire +downstream patch stack and would contaminate the upstream diff. + +Before starting upstream-facing work: + +```bash +git fetch upstream --prune +git fetch origin --prune +git push origin upstream/main:main +git switch -c fix/ upstream/main +``` + +The push keeps the fork's `main` as a fast-forward mirror for GitHub comparisons; +the new branch still names the fetched `upstream/main` commit directly as its +source of truth. If the mirror cannot fast-forward, stop and inspect it rather +than force-pushing or merging downstream history into it. + +Immediately before opening or updating the upstream PR, fetch again and rebase +onto the latest `upstream/main`. Push the topic branch to `origin`, then target +`pingdotgg/t3code:main`. + +For the LastCode copy, start independently from the current downstream base: + +```bash +git fetch origin --prune +git switch -c port/upstream/ origin/lastcode/main +``` + +Cherry-pick the upstream commit when it applies cleanly; otherwise reimplement +the same behavior against LastCode. Validate and review each PR according to its +target repository. An upstream CI result never substitutes for LastCode local +CI, and a LastCode merge never implies that upstream accepted the change. + ## Tag Handling Forks in the same network often reuse release tags such as `v0.0.11`. Fetching @@ -98,15 +170,21 @@ Rules: - `pr//-` - Branches created to inspect or test a specific upstream or fork PR. - `port//` - - Branches used to bring selected work from another fork into `lastCode`. + - Branches used to bring selected work from another fork into LastCode. - `sync//` - Structured sync attempts from a known remote into a branch. - `spike/` - Disposable experiments with no promise of mergeability. - `fix/` - - Upstream-targeted bug fixes branched from `main`. + - Upstream-targeted bug fixes branched from `upstream/main`. +- `feat/` + - Upstream-targeted features branched from `upstream/main`. +- `port/upstream/` + - The independent LastCode copy of an upstream candidate. - `lastcode/` - Fork-only work branched from `lastcode/main`. +- `lastcode/markover/` + - Fork-only Markover integration branched from `lastcode/main`. Examples: @@ -117,7 +195,9 @@ port/aadit/opencode-adapter-parity sync/upstream/2026-04-17 spike/provider-registry fix/subagent-output-interleaving +port/upstream/subagent-output-interleaving lastcode/fork-conventions +lastcode/markover/review-handoff ``` ## Local Tracking References @@ -189,13 +269,43 @@ git cherry-pick ```bash git fetch upstream --prune -git switch main -git pull --ff-only upstream main -git switch -c fix/subagent-output-interleaving +git fetch origin --prune +git push origin upstream/main:main +git switch -c fix/subagent-output-interleaving upstream/main ``` -Push the branch to `origin`, then open the pull request against -`pingdotgg/t3code:main`. +Rebase onto the latest `upstream/main` before opening the pull request. Push the +branch to `origin`, then target `pingdotgg/t3code:main`. + +### Retain an upstream candidate in LastCode + +After preparing the upstream-pure change, make the downstream delivery from a +fresh base: + +```bash +git fetch origin --prune +git switch -c port/upstream/subagent-output-interleaving origin/lastcode/main +git cherry-pick +``` + +Open this PR against `lastcode/main`, link it to the upstream PR, and let the two +reviews and merge decisions proceed independently. + +### Start LastCode-only work + +```bash +git fetch origin --prune +git switch -c lastcode/markover/review-handoff origin/lastcode/main +``` + +Target `lastcode/main`. Pushing runs the quick local gate. Before merge, require +a clean current-head Codex review, no unresolved threads, and a full local-CI +stamp for the exact head and current base. Use the guarded LastCode merge command +rather than merging directly in the GitHub UI. + +An open PR targeting `lastcode/main` pauses nightly promotion, but the automation +continues creating immutable checkpoint tags. Promotion catches up after the PR +queue is empty. ### Inspect a specific pull request @@ -213,8 +323,9 @@ git switch -c pr/upstream/1943-port-token-clamp lastcode/main - If work maps to a concrete PR, use `pr/`. - If work is an explicit sync attempt, use `sync/`. - If work is messy or disposable, use `spike/`. -- If work is an upstream bug fix or feature, branch from `main` and use `fix/` - or another upstream-facing topic name. +- If work is an upstream bug fix or feature, branch from `upstream/main` and use `fix/` + or `feat/`, then create an independent `port/upstream/` branch when LastCode + should retain it. - If work is fork-only, branch from `lastcode/main` and use `lastcode/` or a more specific local prefix. From 24d4410246b987ebddd2df0ecfebbe2f95c7de22 Mon Sep 17 00:00:00 2001 From: Michael Johnston Date: Thu, 13 Aug 2026 18:27:46 -0700 Subject: [PATCH 2/4] docs(lastcode): clarify fork documentation namespace --- .agents/skills/lastcode-pr/SKILL.md | 6 ++++-- docs/lastcode/README.md | 5 +++++ 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/.agents/skills/lastcode-pr/SKILL.md b/.agents/skills/lastcode-pr/SKILL.md index 0627e505dc17..a24efa6b5066 100644 --- a/.agents/skills/lastcode-pr/SKILL.md +++ b/.agents/skills/lastcode-pr/SKILL.md @@ -18,8 +18,10 @@ and should be proposed upstream, switch to `upstream-fix`. 2. Create `lastcode/markover/` for Markover integration or `lastcode/` for other fork-only work from the exact `origin/lastcode/main`. -3. Keep one concern per branch and PR. Put downstream contributor and operations - documentation under `docs/lastcode/`. +3. Keep one concern per branch and PR. Put LastCode-only contributor and + operations documentation under the fork's deliberate `docs/lastcode/` + namespace. Keep product and upstream-facing documentation in the + audience-based directories required by `AGENTS.md`. 4. Never target `main` or `pingdotgg/t3code` from this workflow. ## Implement and Validate diff --git a/docs/lastcode/README.md b/docs/lastcode/README.md index ca3b042dfc63..b3578740e36d 100644 --- a/docs/lastcode/README.md +++ b/docs/lastcode/README.md @@ -5,6 +5,11 @@ patch stack onto upstream nightly releases. Tracking an upstream nightly and building an application are deliberately separate operations: every nightly can be checkpointed, while only selected checkpoints need full local CI and a build. +This directory is the deliberate namespace for LastCode-only contributor and +operations documentation. Product documentation and material intended for an +upstream contribution continue to use T3 Code's audience-based documentation +directories. + ## Documents - [Nightly workflow](nightly-workflow.md): checkpoint tags, rebasing, promotion, From 1d99afee254cf94a58712b0393f73b0d43e143ff Mon Sep 17 00:00:00 2001 From: Michael Johnston Date: Thu, 13 Aug 2026 18:38:53 -0700 Subject: [PATCH 3/4] docs(skills): define GitHub review mechanics --- .../_references/external-review-mechanics.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) diff --git a/.agents/skills/_references/external-review-mechanics.md b/.agents/skills/_references/external-review-mechanics.md index e51ae90fd081..84c7c84c11e7 100644 --- a/.agents/skills/_references/external-review-mechanics.md +++ b/.agents/skills/_references/external-review-mechanics.md @@ -88,3 +88,105 @@ opencode run -m zai-coding-plan/glm-5.1 "$PROMPT" Retry once only when extraction is impossible or ambiguous. - If a reviewer ran forbidden commands, ignore command-derived evidence, salvage file/diff/doc-based findings, and tighten the next prompt. + +## GitHub Review State + +Use GitHub's current head SHA as the review boundary. Do not infer a clean review +from elapsed time, an empty `reviewDecision`, a checkmark, or a review attached to +an older commit. + +Start with one PR snapshot: + +```sh +gh pr view "$PR_NUMBER" --repo "$OWNER/$REPO" \ + --json url,state,isDraft,headRefOid,baseRefOid,mergeStateStatus,reviewDecision,statusCheckRollup +``` + +Read every formal review and issue comment, not only GitHub's default page: + +```sh +gh api --paginate --slurp \ + "repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews?per_page=100" +gh api --paginate --slurp \ + "repos/$OWNER/$REPO/issues/$PR_NUMBER/comments?per_page=100" +``` + +For a Codex trigger comment, inspect its reactions when the review result is not +explicit in a current-head review body. A current Codex eye reaction means review +is still running; a thumbs-up can be the terminal clean signal: + +```sh +gh api --paginate --slurp \ + -H 'Accept: application/vnd.github+json' \ + "repos/$OWNER/$REPO/issues/comments/$COMMENT_ID/reactions?per_page=100" +``` + +Accept Codex as clean only when its result was produced after the latest relevant +push, identifies the exact `headRefOid` (for a formal review, its `commit_id` +matches), and gives an explicit no-issues result or terminal clean reaction. A +generic review wrapper, silence, or absence of inline findings is insufficient by +itself. After a push, request `@codex review` once unless a current request is +already active. + +Read all review threads with GraphQL pagination. `gh api --paginate` supplies the +next `$endCursor`; keep `pageInfo` in the query so it cannot silently truncate at +100 threads: + +```sh +gh api graphql --paginate --slurp \ + -F owner="$OWNER" -F repo="$REPO" -F number="$PR_NUMBER" \ + -f query='query($owner:String!, $repo:String!, $number:Int!, $endCursor:String) { + repository(owner:$owner, name:$repo) { + pullRequest(number:$number) { + headRefOid + reviewThreads(first:100, after:$endCursor) { + nodes { + id + isResolved + isOutdated + comments(first:100) { + nodes { id body path line createdAt author { login } } + pageInfo { hasNextPage endCursor } + } + } + pageInfo { hasNextPage endCursor } + } + } + } + }' +``` + +If a thread's nested `comments.pageInfo.hasNextPage` is true, query that thread's +comments separately with `node(id:$threadId)` and the same paginated connection +pattern before deciding what the thread says. + +Reply with concrete evidence before resolving an addressed or disproved finding: + +```sh +gh api graphql \ + -F threadId="$THREAD_ID" -F body="$REPLY" \ + -f query='mutation($threadId:ID!, $body:String!) { + addPullRequestReviewThreadReply(input:{ + pullRequestReviewThreadId:$threadId, + body:$body + }) { comment { id } } + }' + +gh api graphql \ + -F threadId="$THREAD_ID" \ + -f query='mutation($threadId:ID!) { + resolveReviewThread(input:{threadId:$threadId}) { + thread { id isResolved } + } + }' +``` + +Before merge, take a fresh snapshot and require all of these on the same head: + +- terminal-clean Codex result; +- zero unresolved, non-outdated review threads; +- required checks and local validation are green; +- mergeability is clean and the expected base SHA has not moved. + +After any fix push or rebase, discard the prior review conclusion and repeat the +current-head gate. From ee88138992ae4769b6ae191079f237faa80803b0 Mon Sep 17 00:00:00 2001 From: Michael Johnston Date: Thu, 13 Aug 2026 18:47:15 -0700 Subject: [PATCH 4/4] docs(skills): retain outdated unresolved findings --- .agents/skills/_references/external-review-mechanics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/_references/external-review-mechanics.md b/.agents/skills/_references/external-review-mechanics.md index 84c7c84c11e7..9826ab002184 100644 --- a/.agents/skills/_references/external-review-mechanics.md +++ b/.agents/skills/_references/external-review-mechanics.md @@ -184,7 +184,7 @@ gh api graphql \ Before merge, take a fresh snapshot and require all of these on the same head: - terminal-clean Codex result; -- zero unresolved, non-outdated review threads; +- zero unresolved review threads, including outdated threads; - required checks and local validation are green; - mergeability is clean and the expected base SHA has not moved.