docs(lastcode): define contribution workstreams

.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 review threads, including outdated 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.

.agents/skills/lastcode-pr/SKILL.md

@@ -0,0 +1,72 @@
+---
+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/<topic>` for Markover integration or
+   `lastcode/<topic>` for other fork-only work from the exact
+   `origin/lastcode/main`.
+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
+
+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-url> --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.

.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."

.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/<topic>` or `feat/<topic>` 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/<topic>` 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.

.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."

docs/lastcode/README.md

@@ -5,14 +5,20 @@ 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,
   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