diff --git a/.agents/skills/import-upstream-pr/SKILL.md b/.agents/skills/import-upstream-pr/SKILL.md new file mode 100644 index 000000000000..2430aa5cbad2 --- /dev/null +++ b/.agents/skills/import-upstream-pr/SKILL.md @@ -0,0 +1,156 @@ +--- +name: import-upstream-pr +description: Evaluate, port, validate, and deliver an open-unmerged or closed-unmerged pingdotgg/t3code pull request into LastCode while preserving exact upstream provenance. Use when LastCode wants an existing upstream PR before it merges, after it closes without merge, or when re-evaluating a force-pushed upstream candidate. Do not use to author a new upstream contribution; use upstream-fix. Do not use for a fork-only change with no upstream PR; use lastcode-pr. +--- + +# Import Upstream PR + +Adopt one existing T3 Code PR as an independently owned LastCode change. Treat +the upstream PR as a pinned candidate and evidence source, never as a substitute +for LastCode review, validation, or merge authority. + +## Establish the Boundary + +1. Read the repository `AGENTS.md` and `docs/lastcode/fork-conventions.md`. +2. Read [references/intake-and-evidence.md](references/intake-and-evidence.md) + before capturing the candidate. +3. Keep the product port separate from notes, workflow documentation, and skill + changes. Use separate branches or worktrees. +4. Do not infer permission to push, open a PR, use a browser, or merge. Obtain + the authority required by the repository instructions for each operation. + +## Pin and Inspect the Candidate + +1. Capture the upstream PR URL, state, observed date, title, author, base, exact + `headRefOid`, ordered commits, changed files, checks, reviews, review threads, + linked issues, and closure reason when closed. +2. Force-fetch `pull//head` into a dedicated remote-tracking ref so a + previously cached ref cannot reject a legitimate upstream force-push. + Require the fetched SHA to equal the captured `headRefOid`. Never import a + moving branch name. +3. Derive the complete, oldest-first commit list from the pinned base and head + Git objects. Record its count and require its final SHA to equal + `headRefOid`. Do not use GitHub's PR commits response as the source of truth; + that endpoint is capped at 250 commits even when paginated. +4. Inspect metadata and the full diff before installing dependencies or running + any code controlled by the PR. +5. Check current `upstream/main` and `origin/lastcode/main` for the same behavior, + a replacement, or an incompatible design. +6. Treat a force-pushed upstream head as a new candidate. Range-diff it against + the prior pinned head and repeat the applicable review and validation. + +If `origin/lastcode/main` already contains the exact behavior or an accepted +replacement, stop before creating an evaluation branch and report the candidate +as already adopted or superseded. If only `upstream/main` contains it, decide +whether normal nightly reconciliation is sufficient before creating a manual +port. + +## Decide Eligibility + +- For an open, unmerged PR, decide whether LastCode benefits enough to adopt it + now instead of waiting. +- For a closed, unmerged PR, establish why it closed. Inactivity, contribution + policy, or maintainer bandwidth can be acceptable. Incorrectness, + supersession, or rejected direction requires an explicit LastCode divergence + decision. +- Pause for hidden dependencies, unresolved correctness findings, unclear + product value, unexplained closure, or scope too large to validate + proportionally. + +Record the adoption decision. Upstream CI is supporting evidence only. + +## Build an Isolated Evaluation + +1. Fetch `origin` with pruning and create a clean worktree on + `pr/upstream/-` from the exact `origin/lastcode/main`. +2. Apply the pinned Git graph's ordered commit list with `git cherry-pick -x`. + Preserve authorship and commit boundaries when the stack is coherent. If + the range contains merge commits, stop and plan an ancestry-aware import or + a reimplementation instead of flattening it blindly. +3. Do not merge the upstream PR branch; that drags its base history into + LastCode. +4. If the stack does not fit current LastCode, reimplement only the coherent + behavior and record the upstream PR URL, pinned SHA, and why cherry-pick was + unsuitable. + +Classify integration honestly: + +- changed-path overlap is a risk signal, not a conflict; +- a clean auto-merge still needs semantic review in current LastCode context; +- a textual conflict requires explicit resolution review; +- a clean textual application can still have a semantic conflict. + +Treat every conflict resolution and downstream adaptation as first-party code. + +## Validate the Port + +1. Review every changed line against current LastCode and the linked problem. +2. Walk the affected entry points, clients, providers, contracts, reverse + states, connection modes, performance concerns, and docs. Mark each + non-applicable surface explicitly. +3. Complete dependency installation before starting checks. A partially + completed install is not evidence; require its zero exit and terminal + completion. +4. Run focused behavior tests, targeted lint, the affected package typecheck, + and `git diff --check ` under the repository's + canonical toolchain. A bare `git diff --check` does not inspect an already + committed port. Record the toolchain command and versions with the receipt. +5. Add focused regression tests for backend or automation behavior. Do not run + repo-wide checks merely for intake. +6. For user-visible behavior, obtain browser/computer-use approval and use the + applicable repository app-testing skill against disposable state. Capture + matched LastCode-specific before/after evidence and identify the real client, + viewport, and any authorized fallback accurately. +7. Keep one live app tab when shared browser storage can make cross-tab state + nondeterministic. Verify route, persisted state, and rendered state rather + than trusting a click result alone. + +When accepted, rename the branch to `port/upstream/pr--`. + +## Refresh and Deliver + +1. Immediately before delivery, fetch `origin/lastcode/main` again. If the port + parent moved, rebase the imported commits and rerun affected validation. +2. Before the guarded push, require a clean worktree and record the local head, + destination base, and existing remote topic SHA (or its absence). Then push + in a clean environment so the pre-push `pnpm lastcode:ci:quick` gate sees + ordinary Git/SSH variables. Do not export `GIT_SSH_COMMAND` or inject an SSH + command through Git configuration around the push; those settings flow into + tests that intentionally control `GIT_SSH`. +3. If Quick CI passes but the idle SSH transport subsequently dies, do not + treat its generic success line as an exact-head receipt. Require the local + head to equal the recorded head, the worktree to remain clean, the fetched + destination base to equal the recorded base, and the remote topic SHA (or + absence) to remain unchanged. Only then retry that recorded head with + `--no-verify` and an exact `--force-with-lease` tied to the recorded remote + topic state. Otherwise rerun the guarded push and its hook. +4. Open a PR targeting `lastcode/main` only when explicitly requested. Include + the upstream PR and pinned head, observed state/date, import method, + adaptations, rationale, validation, closure/review context, and published + evidence. +5. For review and merge, follow `lastcode-pr` and + `.agents/skills/_references/external-review-mechanics.md`: require a terminal + clean Codex result for the exact head, zero unresolved threads, and a full + `pnpm lastcode:ci` stamp for the exact head/current base. Merge only through + `pnpm lastcode:merge`. +6. Verify the merged commit on `origin/lastcode/main`. For a squash merge, + compare stable patch IDs so provenance verification does not depend on the + topic commit remaining an ancestor. + +## Reconcile Later Upstream Movement + +- If upstream later merges an identical patch, let normal nightly reconciliation + remove the duplicate. +- If upstream merges a changed version, compare it with the pinned imported head + and port only the desired delta. +- If upstream closes unmerged, retain or remove the behavior according to + LastCode's product decision, not the state transition alone. +- Preserve the upstream URL and pinned SHA in the LastCode PR so future sync work + can explain the source. + +## Handoff + +Report the source PR state and pinned head, destination base and port head, +import method and adaptations, validation and real-client evidence, PR/merge +state, exact-head review result, unresolved-thread count, full-CI stamp, and the +merged commit or remaining blocker. diff --git a/.agents/skills/import-upstream-pr/agents/openai.yaml b/.agents/skills/import-upstream-pr/agents/openai.yaml new file mode 100644 index 000000000000..c5dc80e0ea85 --- /dev/null +++ b/.agents/skills/import-upstream-pr/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Import Upstream PR" + short_description: "Evaluate and port unmerged T3 Code PRs" + default_prompt: "Use $import-upstream-pr to evaluate and import a pinned T3 Code pull request into LastCode." diff --git a/.agents/skills/import-upstream-pr/references/intake-and-evidence.md b/.agents/skills/import-upstream-pr/references/intake-and-evidence.md new file mode 100644 index 000000000000..057a67ef5130 --- /dev/null +++ b/.agents/skills/import-upstream-pr/references/intake-and-evidence.md @@ -0,0 +1,157 @@ +# Intake and Evidence Reference + +Use this reference to create a reproducible receipt before executing upstream +PR code and to keep delivery claims tied to exact commits. + +## Candidate receipt + +Capture PR metadata before fetching or executing the candidate: + +```bash +set -e + +repo=pingdotgg/t3code +pr= + +metadata=$(gh pr view "$pr" --repo "$repo" --json \ + number,title,url,state,isDraft,author,baseRefName,baseRefOid,headRefOid,\ + mergeable,mergeStateStatus,changedFiles,statusCheckRollup,\ + reviewDecision,labels,body,closedAt,mergedAt,updatedAt) + +printf '%s\n' "$metadata" +base_ref=$(printf '%s' "$metadata" | jq -r .baseRefName) +base_sha=$(printf '%s' "$metadata" | jq -r .baseRefOid) +head_sha=$(printf '%s' "$metadata" | jq -r .headRefOid) + +git fetch upstream \ + "+refs/pull/$pr/head:refs/remotes/upstream/pr/$pr" + +fetched_head=$(git rev-parse "refs/remotes/upstream/pr/$pr") +if ! git cat-file -e "$base_sha^{commit}" 2>/dev/null; then + git fetch upstream "$base_sha" || + printf 'exact base SHA was not directly fetchable: %s\n' "$base_sha" >&2 +fi +git cat-file -e "$base_sha^{commit}" || { + printf 'missing pinned base commit: %s\n' "$base_sha" >&2 + exit 1 +} +test "$fetched_head" = "$head_sha" || { + printf 'PR head changed while pinning: expected %s, fetched %s\n' \ + "$head_sha" "$fetched_head" >&2 + exit 1 +} + +if git ls-remote --exit-code --heads upstream \ + "refs/heads/$base_ref" >/dev/null; then + git fetch upstream \ + "+refs/heads/${base_ref}:refs/remotes/upstream/${base_ref}" + current_base_sha=$(git rev-parse "refs/remotes/upstream/$base_ref") +else + current_base_sha=unavailable +fi + +commit_count=$(git rev-list --count "$base_sha..$head_sha") +final_sha=$( + git rev-list --reverse --topo-order "$base_sha..$head_sha" | tail -n 1 +) +test "$commit_count" -gt 0 || { + printf 'pinned PR range is empty\n' >&2 + exit 1 +} +test "$final_sha" = "$head_sha" || { + printf 'commit walk did not end at pinned head: %s\n' "$head_sha" >&2 + exit 1 +} +printf '{"count":%s,"final_sha":"%s","current_base_sha":"%s"}\n' \ + "$commit_count" "$final_sha" "$current_base_sha" +git rev-list --reverse --topo-order "$base_sha..$head_sha" +``` + +Fetching the PR head is independent of fetching its named base branch because +a closed PR can outlive a deleted target branch. The leading `+` refspecs allow +cached PR and live-base refs to follow legitimate force-pushes. `baseRefOid` +can predate the current base tip; require that exact commit object from the PR +history or a direct SHA fetch rather than equating it with `current_base_sha`. +If the named base no longer exists, record it as unavailable instead of failing +the already pinned head. Requiring the fetched PR ref to equal `headRefOid` +detects a head race; restart the capture if it changed. Git's `base..head` walk +is the complete source of truth because the GitHub PR commits endpoint returns +at most 250 commits, while `gh pr view --json commits` exposes only the first 100. Record the oldest-first `--topo-order` list and its count. Also record: + +- observed date and timezone; +- ordered commit SHAs and authors; +- changed file list and diff stat; +- linked issues and claimed behavior; +- all formal reviews and issue comments; +- all review threads, including unresolved and outdated threads; +- upstream check results; +- closure reason or superseding change when closed; and +- current fetched `upstream/main` and `origin/lastcode/main` SHAs. + +Use the paginated review and thread queries in +`.agents/skills/_references/external-review-mechanics.md`. Do not infer a clean +candidate from an empty GitHub summary. + +## Duplicate and integration checks + +Before adoption, compare the candidate against both current destinations: + +- ancestor containment answers whether the exact commit exists; +- stable patch IDs help find identical patches with rewritten commits; +- code/search and linked-issue inspection find replacements with different + implementations; +- path overlap identifies files needing closer review but does not prove a + conflict; +- a merge-tree preview or the isolated cherry-pick establishes textual + applicability; and +- source review establishes semantic compatibility. + +For multiple commits, preserve the pinned Git graph's oldest-first topological +order. Check `git rev-list --merges "$base_sha..$head_sha"` before cherry-pick; +if it is non-empty, plan an ancestry-aware import or reimplementation rather +than flattening merge commits blindly. Use `git range-diff` when the candidate +head changes or when validating a rebased port. + +## Validation receipt + +Tie every result to the exact port head and destination base. Record: + +- toolchain activation command plus Node and package-manager versions; +- dependency install command and terminal success; +- focused commands and test counts; +- `git diff --check ` result for the committed + port range; +- affected-surface matrix with explicit non-applicable entries; +- integrated client, disposable-state boundary, viewport, route/state/rendered + assertions, and before/after artifact paths or published URLs; +- any fallback browser system and the approval that allowed it; and +- clean worktree, local head, remote head, and destination base at publication. + +Do not convert missing evidence into a product pass or failure. Mark the +assertion `blocked`, explain the evidence gap, and either obtain authority for a +fallback or hand it off. + +## LastCode PR body checklist + +Include: + +- upstream PR URL, title, author, observed state/date, and pinned head; +- linked issue and LastCode adoption rationale; +- `cherry-pick -x` or reimplementation method; +- conflict resolutions and LastCode-specific adaptations; +- unresolved upstream review or closure context; +- focused and integrated validation; and +- durable GitHub-hosted visual evidence for UI changes. + +Before merge, refresh the PR snapshot and require the same exact head across the +clean Codex result, zero unresolved threads, full-CI stamp, and merge command. + +After a squash merge, verify stable patch equivalence: + +```bash +git diff | git patch-id --stable +git diff -- | git patch-id --stable +``` + +Matching patch IDs show the validated port became the merged change even though +the original topic commit is not an ancestor of the squashed result.