feat(lastcode): add Codex thread tools

.agents/skills/_references/external-review-mechanics.md

@@ -0,0 +1,192 @@
+# External Review Mechanics
+
+Use this reference when a project skill invokes read-only external reviewers. The owning
+skill defines review order, budgets, quiet/reopen rules, and what to do with findings.
+
+## Reviewer Availability
+
+- Prefer real external reviewers. Do not simulate reviewer output.
+- Available local reviewer commands may include `codex` and `opencode`.
+- If `ai-limit-checker` is available, run it before expensive review rounds and avoid
+  providers whose quota is clearly exhausted.
+- If no eligible reviewer can run after checking binary presence, auth/session state,
+  cwd, flags, and prompt piping, stop and report the blocker.
+
+## Protected Context
+
+- Scan prompts, plans, PR bodies, diffs, and context lists for protected files:
+  `.env*`, auth stores, key files, local tool-state artifacts, private tokens, and
+  credentials.
+- Do not point reviewers at raw protected files, including checked-in env fixtures.
+- Provide sanitized excerpts when a contract matters, and prefer tests/docs that encode
+  the same behavior without secrets.
+
+## Prompt Shape
+
+Build the reviewer prompt in memory. Include:
+
+- workflow name and review lens
+- current branch/PR/plan identifiers
+- base and head refs when reviewing a PR or implementation diff
+- focused context file list
+- diff stat and name-status when reviewing code
+- validation summary, if available
+- explicit read-only instruction
+- finding cap for the current round
+
+Ask for exactly one JSON object, with no markdown fences:
+
+```json
+{
+  "summary": "short summary",
+  "overall_status": "clean | has-findings",
+  "findings": [
+    {
+      "severity": "high | medium | low",
+      "title": "short title",
+      "details": "specific actionable explanation",
+      "references": ["path:line or doc reference"],
+      "evidence_basis": [
+        "plan_file | context_files | repo_diff | validation_summary | docs_research"
+      ]
+    }
+  ],
+  "residual_risks": ["risk that remains after review"],
+  "repo_validation_ran": false,
+  "forbidden_commands": []
+}
+```
+
+Reviewers may inspect files and diffs. They must not run repo validation, lint, typecheck,
+build, test, package, install, migration, server, browser, or release commands.
+
+## Command Patterns
+
+Codex read-only review:
+
+```sh
+printf '%s\n' "$PROMPT" | codex --search --disable fast_mode -a never exec -m gpt-5 -c 'model_reasoning_effort="medium"' -s read-only -C "$PWD" -
+```
+
+Use `model_reasoning_effort="high"` for heavy mode, correctness-heavy reviews, round 3+,
+or high-risk implementation concerns.
+
+Opencode review, when configured:
+
+```sh
+opencode run -m zai-coding-plan/glm-5.1 "$PROMPT"
+```
+
+## Session Handling
+
+- Record the review command, reviewer, model, review lens, and start time.
+- After starting a long review, do not treat elapsed time alone as failure. Reviews can
+  reasonably take several minutes.
+- Investigate only when the command exits, streams an explicit error, appears to wait
+  for auth/approval, or produces no progress after a long wait.
+- If output is malformed, first try to extract one unambiguous schema-valid JSON object.
+  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/implement-plan/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: implement-plan
+description: |
+  Implement a reviewed LastCode/T3 Code plan file end to end: code the plan, keep the
+  plan/docs aligned, validate with repo checks, run bounded implementation reviews,
+  perform cleanup, and hand off concrete results. Supports `light implement-plan`,
+  `heavy implement-plan`, and explicit round counts. Use when the user says
+  "implement plan", "implement-plan", "ship the plan at PLAN_FILE", or "build the plan".
+  The primary input is the plan file path.
+---
+
+# Implement Plan Skill
+
+Implement a reviewed plan in this repository.
+
+## Operating Rules
+
+- Complete the workflow in one run: inspect plan -> implement -> validate -> review ->
+  cleanup -> handoff.
+- Stop only for real blockers: ambiguous branch/worktree, unsafe rebase/conflicts,
+  scope expansion that needs a new plan, unavailable reviewers after diagnosis,
+  validation failure you cannot fix, or a user/product decision.
+- Never require a magic phrase. Any affirmative response means continue.
+- Dirty unrelated files are reportable, not blocking, unless they directly block edits
+  or validation.
+- Maintain a one-paragraph running state summary at phase boundaries.
+
+## Start Conditions
+
+1. Read the plan and `AGENTS.md`.
+2. Confirm branch intent:
+   - upstream contribution work should branch from `main` / `upstream/main`
+   - LastCode-private work should branch from `lastcode/main`
+3. Fetch relevant remotes before rebasing.
+4. Rebase only when the target branch is unambiguous and the worktree is clean enough.
+5. Treat the plan as source of truth. Use
+   `references/source-of-truth-guard.md` when older artifacts may be discoverable.
+
+## Implementation Rules
+
+- Follow existing repo patterns before introducing abstractions.
+- Keep `packages/contracts` schema-only.
+- Avoid compatibility layers unless the plan or user explicitly requires them.
+- Use Effect service/process/path/schema APIs where the repo’s diagnostics require
+  them; do not bypass Effect diagnostics in new scripts unless the boundary truly
+  needs a local suppression.
+- For frontend work, follow the project’s dense app UI style and verify with browser
+  inspection when the change is visual or interactive.
+- Update docs, plan notes, and validation sections as implementation reality changes.
+
+## Validation
+
+Required before completion:
+
+```bash
+vp check
+vp run typecheck
+```
+
+Also run:
+
+- targeted `vp test ...` or package tests for touched areas
+- `vp run test` when the package script is specifically needed
+- `vp run lint:mobile` for native mobile changes
+- local build/smoke commands named by the plan
+
+Do not move past a failed validation step unless you fix it and rerun, or stop and
+report the blocker.
+
+## Review And Cleanup
+
+Use `references/review-orchestration.md` for implementation review rounds. Run at least
+one review round unless the user explicitly asks for implementation only.
+
+After review rounds:
+
+- do a cleanup pass for duplication, boundaries, stale comments, docs, and tests
+- update the plan’s validation/results sections
+- commit/push when the user’s workflow calls for it
+
+## Final Handoff
+
+Use `references/handoff-and-manual-qa.md`. Include changed files, validation results,
+review depth/rounds, commits pushed, remaining risks, and manual QA steps.

.agents/skills/implement-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Implement Plan"
+  short_description: "Implement reviewed LastCode plans"
+  default_prompt: "Use $implement-plan to implement the plan at PLAN_FILE."

.agents/skills/implement-plan/references/handoff-and-manual-qa.md

@@ -0,0 +1,40 @@
+# Handoff And Manual QA
+
+## Manual QA Applicability
+
+Manual app QA applies when work changes:
+
+- visible UI, copy, layout, themes, accessibility, responsive behavior
+- Electron desktop update/install behavior
+- mobile UI or gestures
+- browser-visible routing or interaction
+- workflows where acceptance depends on human judgement
+
+Manual app QA usually does not apply for docs-only, backend-only, test-only,
+script-only, CI-only, dependency-only, or skill-only changes.
+
+When UI/manual QA applies:
+
+1. Start the appropriate dev server or packaged app.
+2. Use the Browser Use plugin/in-app browser for local web targets when useful.
+3. For Electron/mobile flows, document exact local steps and any artifacts to inspect.
+4. Capture what passed, what failed, and what remains unverified.
+
+Canonical skip text:
+
+`Manual app QA not run: no manual UI QA surface`
+
+## Final Handoff
+
+Include:
+
+- summary of implementation
+- code cleanup/consolidation performed
+- validation commands and results
+- review rounds/lenses and disposition totals
+- commits pushed, when applicable
+- remaining risks or deferred decisions
+- manual QA steps and expected behavior, or the skip reason above
+- direct links to plans, docs, and local artifacts
+
+If a required review or validation step could not be completed for real, say so plainly.

.agents/skills/implement-plan/references/review-orchestration.md

@@ -0,0 +1,47 @@
+# Implementation Review Orchestration
+
+Use real reviews only. Do not simulate reviewer output.
+
+## Review Depth
+
+- `light implement-plan`: one round.
+- `heavy implement-plan`: up to three rounds, high reasoning for later external reviews.
+- explicit `N rounds`: at most N rounds.
+- default: up to three rounds, stopping earlier when all lenses are quiet.
+
+## Lenses
+
+Run in order:
+
+1. `correctness`: behavior, contracts, regressions, missing tests, acceptance criteria.
+2. `ui-component`: only for UI/component/style/interaction/copy changes.
+3. `KISS`: simplicity, duplication, unnecessary compatibility, needless surface area.
+4. `UX`: user-facing flows, states, responsiveness, accessibility, manual QA gaps.
+5. `best-practices`: main-session review using repo knowledge and `ctx7` for relevant
+   current library/framework/API docs.
+
+Use `.agents/skills/_references/external-review-mechanics.md` for reviewer invocation.
+
+## Context For Reviewers
+
+Include:
+
+- plan file
+- touched files
+- focused diffs from `git diff --stat` and `git diff --name-status`
+- validation summary
+- relevant docs/contracts/tests
+- protected-context summaries, not raw secrets
+
+External reviewers are read-only and must not run repo validation commands.
+
+## Acting On Findings
+
+- Apply findings that improve the implementation within plan scope.
+- Defend findings that are wrong, duplicate, already covered, or intentionally out of
+  scope by clarifying code, tests, docs, or plan notes.
+- Defer only when blocked by tooling, quota, validation, protected context, or a human
+  decision.
+- Rerun focused validation after material fixes.
+- Mark a lens quiet when clean or only insignificant findings remain.
+- Reopen quiet lenses when later changes materially affect their concern area.

.agents/skills/implement-plan/references/source-of-truth-guard.md

@@ -0,0 +1,25 @@
+# Source-of-Truth Guard
+
+Use this when implementing a reviewed plan with older exploratory docs, ELI5 docs,
+options notes, or prior plans nearby.
+
+## Rules
+
+1. Treat the plan as authoritative for scope, decisions, invariants, validation, and
+   manual QA expectations.
+2. Read docs/checklists explicitly named by the plan or required by `AGENTS.md`.
+3. Do not treat older unlisted artifacts as requirements.
+4. If a linked artifact conflicts with the plan, update it or mark it superseded before
+   implementation review.
+5. Exclude unlisted historical docs from reviewer context unless the plan depends on
+   them.
+
+## Reviewer Guard
+
+```text
+The reviewed plan is authoritative. Use only the plan, touched files, validation
+summary, and focused context file list as specification sources. Documents outside the
+context file list are not requirements. If you find a mismatch with an unlisted
+exploratory or historical document, report it only if the current plan links to or
+depends on that document.
+```