feat(skills): automate selfhost upstream upgrades

[aryasaatvik]

Summary

Add a guarded project skill for carrying an Executor fork from upstream rebase through reviewed promotion, linked-selfhost refresh, host reconciliation, deployment, and live MCP verification.

Flow

inspect exact refs and checkout health
  -> prepare isolated rebase candidate
  -> validate and review
  -> confirm exact-lease dev promotion
  -> detach selfhost at promoted SHA
  -> reconcile host through a separate PR when needed
  -> confirm migrations and production deploy
  -> verify through Executor MCP and Worker telemetry

The bundled preflight is read-only and checks checkout cleanliness, branch/detached state, fork divergence, remote-ref alignment, and all hosted link:@executor-js/* targets.

Safety boundaries

• Promotion and deployment remain separate explicit approval gates.
• Semantic conflicts, migration ambiguity, dirty worktrees, and changed leases stop the workflow.
• Host changes use a separate reviewed PR rather than uncommitted production edits.
• Cloudflare mutations use Wrangler; live Executor validation uses MCP, never the Executor CLI.

Validation

• Skill structure validator passed.
• Scoped oxfmt --check passed.
• Scoped oxlint --deny-warnings passed.
• Scoped pinned tsgo check passed.
• Live preflight reported 21 correctly linked packages and the expected stale upstream snapshot.
• Negative preflight returned a blocking exit for a missing host checkout.

Repository-wide gates were also attempted. Existing baseline failures remain in .scratchpad formatting/lint, SVG module resolution during plugin-toolkits typecheck, and the optional better-sqlite3 semantic-search test dependency.

[greptile-apps]

Greptile Summary

The PR adds a guarded skill for upgrading the self-hosted Executor fork from upstream rebase through deployment and live verification.

• Separates inspection, preparation, promotion, and deployment into explicit approval phases.
• Documents rebase, host reconciliation, migration, deployment, and rollback procedures.
• Adds a read-only preflight that validates checkout state, ref alignment, divergence, and linked package targets.
• Replaces environment-specific paths with configurable checkout discovery and correctly canonicalizes both sides of link containment checks.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
.agents/skills/executor-selfhost-upgrade/SKILL.md	Defines the phased upgrade workflow, approval boundaries, shared invariants, and stopping conditions.
.agents/skills/executor-selfhost-upgrade/references/rebase.md	Documents isolated candidate preparation, conflict handling, validation, review, and exact-lease promotion.
.agents/skills/executor-selfhost-upgrade/references/deploy.md	Documents linked-source refresh, host reconciliation, migration approval, deployment, verification, and rollback handling.
.agents/skills/executor-selfhost-upgrade/references/topology.md	Describes the checkout topology using neutral, configurable discovery without retaining private environment details.
.agents/skills/executor-selfhost-upgrade/scripts/preflight.ts	Implements read-only repository, ref, divergence, and package-link checks; the previous asymmetric canonicalization defect is corrected.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Inspect[Inspect refs and checkout health] --> Prepare[Prepare isolated rebase candidate]
  Prepare --> Validate[Validate and review]
  Validate --> Promote{Promotion approved?}
  Promote -->|Yes| Dev[Promote dev with exact lease]
  Promote -->|No| Stop1[Stop]
  Dev --> Selfhost[Detach selfhost at promoted SHA]
  Selfhost --> Host[Reconcile hosted repository]
  Host --> Deploy{Migration and deployment approved?}
  Deploy -->|Yes| Production[Run migrations and deploy]
  Deploy -->|No| Stop2[Stop]
  Production --> Verify[Verify through MCP and telemetry]

Loading

_{Reviews (2): Last reviewed commit: "fix(skills): make selfhost preflight por..." | Re-trigger Greptile}