From 35914bd15c1fbbcca34c08b6214af4c357e07bf8 Mon Sep 17 00:00:00 2001 From: Maksim Zayats Date: Mon, 1 Jun 2026 09:21:49 +0100 Subject: [PATCH 1/2] docs: improve upstream sync workflow guidance --- .agents/commands/upstream-sync.md | 31 +++++++++++-- .agents/skills/upstream-sync/SKILL.md | 46 +++++++++++++++++++ .../skills/upstream-sync/agents/openai.yaml | 4 ++ 3 files changed, 78 insertions(+), 3 deletions(-) create mode 100644 .agents/skills/upstream-sync/SKILL.md create mode 100644 .agents/skills/upstream-sync/agents/openai.yaml diff --git a/.agents/commands/upstream-sync.md b/.agents/commands/upstream-sync.md index 472808604..5ae46c163 100644 --- a/.agents/commands/upstream-sync.md +++ b/.agents/commands/upstream-sync.md @@ -10,6 +10,8 @@ Refresh `origin/upstream` from `superset-sh/superset:main`, then open a proxy-br This command is shared from `.agents/commands/`. `.claude/commands` and `.cursor/commands` are symlinks to that directory, so do not duplicate this file elsewhere. +The companion skill is `.agents/skills/upstream-sync/SKILL.md`. When this workflow changes, update the slash command and the skill together. + ## Arguments - `--mirror-only` — fast-forward `origin/upstream`, then stop before creating a PR. @@ -32,6 +34,7 @@ This command is shared from `.agents/commands/`. `.claude/commands` and `.cursor - Do not include agent attribution in branch names, commit messages, PR titles, PR bodies, or comments. - Start from a clean worktree. If there are local changes, stop and report them before fetching, switching branches, or merging. - Follow the repository rules in `AGENTS.md`; do not duplicate those rules in this command. +- Keep the sync PR scoped to upstream content plus necessary conflict and fork-delta resolutions. Put follow-up process documentation changes on a separate branch from `main`. ## Workflow @@ -215,6 +218,20 @@ Before resolving conflicts and before treating a conflict-free merge as ready, r Treat those files as the source of truth. If a sync exposes a new intentional O3-vs-upstream behavior difference, update `docs/internal/fork-deltas/registry.md` in the sync PR instead of adding a one-off checklist here. +After resolving conflicts, and even when the merge is conflict-free, review the final proxy-branch diff for upstream identity leaking into O3 runtime code: + +```bash +git diff origin/main...HEAD -- apps packages | \ + rg -n '(@superset|superset-cli|superset-sh|Watt|watt)' || true +``` + +Treat matches as review prompts, not automatic failures. Preserve O3 package scopes, product names, domains, env prefixes, protocols, persisted paths, and OAuth client IDs. The current O3 CLI OAuth client id is `o3-code-cli` in: + +- `packages/cli/src/lib/auth.ts` +- `packages/host-service/src/providers/auth/ConfigFileSessionTokenSource/ConfigFileSessionTokenSource.ts` + +If upstream adds a trusted-client guard or similar identity-sensitive logic, map upstream IDs to the O3 equivalent before validating. + Useful conflict checks: ```bash @@ -232,12 +249,19 @@ For an upstream content sync, run: bun run lint:fix bun run lint bun run typecheck +if [ ! -f packages/pty-daemon/dist/pty-daemon.js ]; then + bun run build +fi bun test ``` -Run targeted tests for any conflict area. Run `bun run build` when upstream touches packaging, Next apps, Electron, shared config, or release workflows. +Run targeted tests for any conflict area. Run `bun run build` before the final `bun test` attempt when upstream touches desktop, host-service, daemon, packaging, release, shared config, or Next app behavior. + +Some repository tests require generated build artifacts. If `bun test` still fails because `packages/pty-daemon/dist/pty-daemon.js` is missing, run `bun run build` and rerun `bun test` once. + +If validation fails from an unrelated existing issue, do not fix unrelated areas in the sync PR. Capture the exact command, first failure class, final summary, and exit code in the PR body. If no targeted tests exist for the touched area, say that explicitly. -If validation fails from an unrelated existing issue, capture the exact command and failure in the PR body. +If you amend the merge commit after validation, rerun at least `bun run lint:fix`, `bun run lint`, and `bun run typecheck`. Rerun `bun run build` when the amendment could affect build output; a Turbo cache replay is acceptable. ### 8. Open The PR @@ -262,11 +286,12 @@ cat >/tmp/upstream-sync-pr.md < +- Fork-delta decisions: - Fork-delta registry updates: - Merge method required: merge commit, not squash/rebase. ## Validation -- +- ## Follow-Ups - diff --git a/.agents/skills/upstream-sync/SKILL.md b/.agents/skills/upstream-sync/SKILL.md new file mode 100644 index 000000000..578c6d7d0 --- /dev/null +++ b/.agents/skills/upstream-sync/SKILL.md @@ -0,0 +1,46 @@ +--- +name: upstream-sync +description: Use when refreshing the O3 Code upstream mirror from superset-sh/superset, opening or updating a sync/upstream-* PR, resolving upstream merge conflicts, validating an upstream sync, or improving .agents/commands/upstream-sync.md. +--- + +# Upstream Sync + +## Core Rule + +Read `.agents/commands/upstream-sync.md` first and follow it. This skill is a short companion for agent behavior and lessons from real sync runs. If this skill and the command diverge, update them together. + +## Operating Mode + +- Start from a clean worktree and stop on unrelated local changes. +- Keep `origin/upstream` pure. Resolve conflicts only on a proxy branch based on `origin/main`. +- When the refreshed mirror leaves `main` behind and there is no duplicate open sync PR, open the proxy-branch PR without asking for extra confirmation. +- Keep the sync PR limited to upstream changes plus necessary conflict and fork-delta resolutions. +- If follow-up process docs are requested after a sync PR is open, use a separate branch from `main` instead of adding unrelated docs to the sync PR. + +## Fork-Delta Checks + +- Read `AGENTS.md`, `docs/internal/fork-deltas/README.md`, and `docs/internal/fork-deltas/registry.md` before resolving conflicts or declaring a conflict-free merge ready. +- Preserve O3 identity in code and config. Review upstream-introduced package scopes, binary names, env prefixes, product strings, domains, protocols, persisted paths, and OAuth client IDs. +- Current O3 CLI OAuth client id is `o3-code-cli`; verify against `packages/cli/src/lib/auth.ts` and `packages/host-service/src/providers/auth/ConfigFileSessionTokenSource/ConfigFileSessionTokenSource.ts` if upstream changes auth client guards. +- Run an identity scan on the final proxy-branch diff: + +```bash +git diff origin/main...HEAD -- apps packages | rg -n '(@superset|superset-cli|superset-sh|Watt|watt)' || true +``` + +Treat matches as review prompts, not automatic failures. Superset references in sync metadata can be fine; product identity in runtime code usually needs an O3 mapping. + +## Validation + +- Run the validation commands from `.agents/commands/upstream-sync.md`. +- Run `bun run build` before rerunning `bun test` if the test suite reports a missing `packages/pty-daemon/dist/pty-daemon.js` bundle, or when upstream touches desktop, host-service, daemon, packaging, release, shared config, or Next app behavior. +- Run targeted tests for touched or conflicted areas. If no targeted tests exist, state that explicitly in the PR body. +- If `bun test` fails in unrelated existing areas, do not fix unrelated failures in the sync PR. Capture the exact command, first failure class, final summary, and exit code in the PR body. +- After amending the merge commit, rerun `bun run lint:fix`, `bun run lint`, and `bun run typecheck`. Ensure any build result applies to the final commit; a Turbo cache replay is acceptable. + +## PR Notes + +- Include the old and new mirror SHAs, the Superset range, and whether `origin/upstream` was fast-forwarded. +- List conflict files and the exact fork-delta choices made, especially identity mappings. +- Include validation successes and any unrelated failures without agent attribution. +- Keep the merge method note explicit: merge commit required, no squash or rebase. diff --git a/.agents/skills/upstream-sync/agents/openai.yaml b/.agents/skills/upstream-sync/agents/openai.yaml new file mode 100644 index 000000000..ff5792533 --- /dev/null +++ b/.agents/skills/upstream-sync/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Upstream Sync" + short_description: "Sync the Superset mirror into O3 Code safely." + default_prompt: "Run the upstream sync workflow and open a safe proxy-branch PR." From 07a834a97c134a9045eb8a0d5f9d9e4bfb134795 Mon Sep 17 00:00:00 2001 From: Maksim Zayats Date: Mon, 1 Jun 2026 10:05:35 +0100 Subject: [PATCH 2/2] docs: keep upstream sync guidance in command --- .agents/commands/upstream-sync.md | 2 - .agents/skills/upstream-sync/SKILL.md | 46 ------------------- .../skills/upstream-sync/agents/openai.yaml | 4 -- 3 files changed, 52 deletions(-) delete mode 100644 .agents/skills/upstream-sync/SKILL.md delete mode 100644 .agents/skills/upstream-sync/agents/openai.yaml diff --git a/.agents/commands/upstream-sync.md b/.agents/commands/upstream-sync.md index 5ae46c163..b0e16402c 100644 --- a/.agents/commands/upstream-sync.md +++ b/.agents/commands/upstream-sync.md @@ -10,8 +10,6 @@ Refresh `origin/upstream` from `superset-sh/superset:main`, then open a proxy-br This command is shared from `.agents/commands/`. `.claude/commands` and `.cursor/commands` are symlinks to that directory, so do not duplicate this file elsewhere. -The companion skill is `.agents/skills/upstream-sync/SKILL.md`. When this workflow changes, update the slash command and the skill together. - ## Arguments - `--mirror-only` — fast-forward `origin/upstream`, then stop before creating a PR. diff --git a/.agents/skills/upstream-sync/SKILL.md b/.agents/skills/upstream-sync/SKILL.md deleted file mode 100644 index 578c6d7d0..000000000 --- a/.agents/skills/upstream-sync/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: upstream-sync -description: Use when refreshing the O3 Code upstream mirror from superset-sh/superset, opening or updating a sync/upstream-* PR, resolving upstream merge conflicts, validating an upstream sync, or improving .agents/commands/upstream-sync.md. ---- - -# Upstream Sync - -## Core Rule - -Read `.agents/commands/upstream-sync.md` first and follow it. This skill is a short companion for agent behavior and lessons from real sync runs. If this skill and the command diverge, update them together. - -## Operating Mode - -- Start from a clean worktree and stop on unrelated local changes. -- Keep `origin/upstream` pure. Resolve conflicts only on a proxy branch based on `origin/main`. -- When the refreshed mirror leaves `main` behind and there is no duplicate open sync PR, open the proxy-branch PR without asking for extra confirmation. -- Keep the sync PR limited to upstream changes plus necessary conflict and fork-delta resolutions. -- If follow-up process docs are requested after a sync PR is open, use a separate branch from `main` instead of adding unrelated docs to the sync PR. - -## Fork-Delta Checks - -- Read `AGENTS.md`, `docs/internal/fork-deltas/README.md`, and `docs/internal/fork-deltas/registry.md` before resolving conflicts or declaring a conflict-free merge ready. -- Preserve O3 identity in code and config. Review upstream-introduced package scopes, binary names, env prefixes, product strings, domains, protocols, persisted paths, and OAuth client IDs. -- Current O3 CLI OAuth client id is `o3-code-cli`; verify against `packages/cli/src/lib/auth.ts` and `packages/host-service/src/providers/auth/ConfigFileSessionTokenSource/ConfigFileSessionTokenSource.ts` if upstream changes auth client guards. -- Run an identity scan on the final proxy-branch diff: - -```bash -git diff origin/main...HEAD -- apps packages | rg -n '(@superset|superset-cli|superset-sh|Watt|watt)' || true -``` - -Treat matches as review prompts, not automatic failures. Superset references in sync metadata can be fine; product identity in runtime code usually needs an O3 mapping. - -## Validation - -- Run the validation commands from `.agents/commands/upstream-sync.md`. -- Run `bun run build` before rerunning `bun test` if the test suite reports a missing `packages/pty-daemon/dist/pty-daemon.js` bundle, or when upstream touches desktop, host-service, daemon, packaging, release, shared config, or Next app behavior. -- Run targeted tests for touched or conflicted areas. If no targeted tests exist, state that explicitly in the PR body. -- If `bun test` fails in unrelated existing areas, do not fix unrelated failures in the sync PR. Capture the exact command, first failure class, final summary, and exit code in the PR body. -- After amending the merge commit, rerun `bun run lint:fix`, `bun run lint`, and `bun run typecheck`. Ensure any build result applies to the final commit; a Turbo cache replay is acceptable. - -## PR Notes - -- Include the old and new mirror SHAs, the Superset range, and whether `origin/upstream` was fast-forwarded. -- List conflict files and the exact fork-delta choices made, especially identity mappings. -- Include validation successes and any unrelated failures without agent attribution. -- Keep the merge method note explicit: merge commit required, no squash or rebase. diff --git a/.agents/skills/upstream-sync/agents/openai.yaml b/.agents/skills/upstream-sync/agents/openai.yaml deleted file mode 100644 index ff5792533..000000000 --- a/.agents/skills/upstream-sync/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Upstream Sync" - short_description: "Sync the Superset mirror into O3 Code safely." - default_prompt: "Run the upstream sync workflow and open a safe proxy-branch PR."