symphony-box 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Upstash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @upstash/symphony-box
+
+CLI to set up [Symphony](https://github.com/odysseus0/symphony) (OpenAI Codex orchestrator) on an [Upstash Box](https://upstash.com/docs/box/overall/getstarted) for a GitHub repo connected to a Linear project.
+
+## What it does
+
+1. Checks your Linear project for required workflow states and creates any that are missing
+2. Creates an Upstash Box with your credentials
+3. Installs system dependencies, Codex, and mise on the box
+4. Clones your repo and writes a `WORKFLOW.md` config for Symphony
+5. Clones and builds Symphony on the box
+6. Starts Symphony
+
+Once running, Symphony polls your Linear project and autonomously works on tickets using Codex.
+
+## Usage
+
+```bash
+npx symphony-box
+```
+
+You will be prompted for:
+
+- **Upstash Box API key** — from [console.upstash.com](https://console.upstash.com)
+- **OpenAI API key** — used by Codex to work on tickets
+- **Linear API key** — to poll and update tickets
+- **GitHub token** — requires read/write access for contents and pull requests
+
+Then select a GitHub repo and a Linear project from the list.
+
+## Flags
+
+All prompts can be skipped via flags or environment variables:
+
+| Flag                    | Env var               | Description                          |
+| ----------------------- | --------------------- | ------------------------------------ |
+| `--upstash-box-api-key` | `UPSTASH_BOX_API_KEY` | Upstash Box API key                  |
+| `--openai-api-key`      | `OPENAI_API_KEY`      | OpenAI API key                       |
+| `--linear-api-key`      | `LINEAR_API_KEY`      | Linear API key                       |
+| `--github-token`        | `GITHUB_TOKEN`        | GitHub token                         |
+| `--repo-url`            | `REPO_URL`            | GitHub repo URL (skip selection)     |
+| `--project-name`        | `LINEAR_PROJECT_NAME` | Linear project name (skip selection) |
+
+## Required Linear workflow states
+
+Symphony requires these states to exist in your Linear team:
+
+- **Rework** — reviewer requested changes
+- **Human Review** — PR is ready for human approval
+- **Merging** — approved; Symphony will merge the PR
+
+The CLI will detect missing states and offer to create them.
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { intro, outro, text, select, confirm, isCancel, cancel, spinner, log } from "@clack/prompts";
+import { Command } from "commander";
+import chalk from "chalk";
+import { run_init } from "./init.js";
+
+const program = new Command();
+
+program
+  .name("symphony-box")
+  .description("Set up Symphony on an Upstash Box for a GitHub repo")
+  .option("--upstash-box-api-key <key>", "Upstash Box API key")
+  .option("--openai-api-key <key>", "OpenAI API key")
+  .option("--linear-api-key <key>", "Linear API key")
+  .option("--github-token <token>", "GitHub token")
+  .option("--repo-url <url>", "GitHub repo URL (skip selection)")
+  .option("--project-name <name>", "Linear project name (skip selection)")
+  .parse(process.argv);
+
+const opts = program.opts();
+
+function checkCancel(result) {
+  if (isCancel(result)) {
+    cancel("Cancelled.");
+    process.exit(0);
+  }
+  return result;
+}
+
+async function promptText(message, envKey, flagValue, placeholder) {
+  const value = flagValue ?? process.env[envKey];
+  if (value) return value;
+  return checkCancel(
+    await text({ message, placeholder, validate: (v) => (v ? undefined : "Required") })
+  );
+}
+
+async function pickRepo(githubToken) {
+  const fixed = opts.repoUrl ?? process.env.REPO_URL;
+  if (fixed) return { repoUrl: fixed, repoName: fixed.split("/").pop().replace(/\.git$/, "") };
+
+  const s = spinner();
+  s.start("Fetching your GitHub repos...");
+  const res = await fetch("https://api.github.com/user/repos?per_page=100&sort=updated", {
+    headers: { Authorization: `Bearer ${githubToken}`, Accept: "application/vnd.github+json" },
+  });
+  const repos = await res.json();
+  s.stop("Repos loaded");
+
+  const selected = checkCancel(
+    await select({
+      message: "Select a GitHub repo",
+      options: repos.map((r) => ({
+        value: { repoUrl: r.clone_url, repoName: r.name },
+        label: r.full_name,
+        hint: r.private ? "private" : "public",
+      })),
+    })
+  );
+  return selected;
+}
+
+async function pickLinearProject(linearApiKey) {
+  const fixed = opts.projectName ?? process.env.LINEAR_PROJECT_NAME;
+  if (fixed) return fixed;
+
+  const s = spinner();
+  s.start("Fetching your Linear projects...");
+  const res = await fetch("https://api.linear.app/graphql", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: linearApiKey },
+    body: JSON.stringify({ query: "{ projects { nodes { name } } }" }),
+  });
+  const json = await res.json();
+  s.stop("Projects loaded");
+
+  return checkCancel(
+    await select({
+      message: "Select a Linear project",
+      options: json.data.projects.nodes.map((p) => ({ value: p.name, label: p.name })),
+    })
+  );
+}
+
+async function main() {
+  intro(chalk.cyan("Symphony Box Setup"));
+
+  const upstashBoxApiKey = await promptText("Upstash Box API key", "UPSTASH_BOX_API_KEY", opts.upstashBoxApiKey);
+
+  const openaiApiKey = await promptText("OpenAI API key", "OPENAI_API_KEY", opts.openaiApiKey, "sk-...");
+  const linearApiKey = await promptText("Linear API key", "LINEAR_API_KEY", opts.linearApiKey, "lin_api_...");
+  const githubToken = await promptText("GitHub token (requires read/write access for contents and pull requests)", "GITHUB_TOKEN", opts.githubToken, "ghp_...");
+
+  const { repoUrl, repoName } = await pickRepo(githubToken);
+  const linearProjectName = await pickLinearProject(linearApiKey);
+
+  const s = spinner();
+  s.start("Starting...");
+
+  try {
+    const { boxId, stream } = await run_init(
+      { upstashBoxApiKey, openaiApiKey, linearApiKey, githubToken, repoUrl, repoName, linearProjectName },
+      {
+        onStep: (_step, message) => s.message(message),
+        onMissingStates: async (missing) => {
+          s.stop();
+          const names = missing.map((s) => `  • ${s.name}`).join("\n");
+          const ok = checkCancel(
+            await confirm({
+              message: `These workflow states are missing and required by Symphony:\n${names}\n  Create them?`,
+            })
+          );
+          s.start();
+          return ok;
+        },
+      }
+    );
+
+    s.stop("Done");
+
+    // Stream Symphony output until disconnected
+    try {
+      for await (const chunk of stream) {
+        if (chunk.type === "output") process.stdout.write(chunk.data);
+      }
+    } catch {
+      // Stream disconnected — Symphony keeps running on the box
+    }
+
+    outro(chalk.green("Symphony is running!") + `\n\n  Box ID: ${chalk.bold(boxId)}`);
+  } catch (err) {
+    s.stop("Failed");
+    log.error(chalk.red(err.message));
+    process.exit(1);
+  }
+}
+
+main();

package/init.js

@@ -0,0 +1,137 @@
+import { Box } from "@upstash/box";
+import { buildWorkflow } from "./workflow.js";
+
+const SYMPHONY_URL = "https://github.com/odysseus0/symphony";
+const MISE = "/home/boxuser/.local/bin/mise";
+
+async function linearQuery(linearApiKey, query, variables) {
+  const res = await fetch("https://api.linear.app/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: linearApiKey,
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  const json = await res.json();
+  if (json.errors) throw new Error(JSON.stringify(json.errors));
+  return json.data;
+}
+
+const REQUIRED_STATES = [
+  { name: "Rework", color: "#db6e1f" },
+  { name: "Human Review", color: "#da8b0d" },
+  { name: "Merging", color: "#0f783c" },
+];
+
+async function setupLinear(linearApiKey, projectName, onMissingStates) {
+  const data = await linearQuery(
+    linearApiKey,
+    `{ projects { nodes { name slugId teams { nodes { id } } } } }`
+  );
+  const project = data.projects.nodes.find((p) => p.name === projectName);
+  if (!project) throw new Error(`Linear project "${projectName}" not found`);
+
+  const teamId = project.teams.nodes[0].id;
+
+  const statesData = await linearQuery(
+    linearApiKey,
+    `{ workflowStates { nodes { name team { id } } } }`
+  );
+  const existing = statesData.workflowStates.nodes
+    .filter((s) => s.team?.id === teamId)
+    .map((s) => s.name);
+
+  const missing = REQUIRED_STATES.filter((s) => !existing.includes(s.name));
+
+  if (missing.length > 0) {
+    const confirmed = await onMissingStates(missing);
+    if (!confirmed)
+      throw new Error("Aborted: required workflow states not created.");
+
+    for (const state of missing) {
+      await linearQuery(
+        linearApiKey,
+        `mutation($input: WorkflowStateCreateInput!) { workflowStateCreate(input: $input) { success } }`,
+        {
+          input: {
+            teamId,
+            name: state.name,
+            type: "started",
+            color: state.color,
+          },
+        }
+      );
+    }
+  }
+
+  return { slugId: project.slugId };
+}
+
+export async function run_init(
+  {
+    upstashBoxApiKey,
+    openaiApiKey,
+    linearApiKey,
+    githubToken,
+    repoUrl,
+    repoName,
+    linearProjectName,
+  },
+  { onStep = () => {}, onMissingStates = async () => true } = {}
+) {
+  onStep("linear", "Checking Linear project and workflow states...");
+  const { slugId } = await setupLinear(
+    linearApiKey,
+    linearProjectName,
+    onMissingStates
+  );
+
+  onStep("workflow", `Building WORKFLOW.md (slug: ${slugId})...`);
+  const workflow = buildWorkflow(slugId, repoUrl);
+
+  onStep("box", "Creating Upstash Box...");
+  const box = await Box.create({
+    apiKey: upstashBoxApiKey,
+    runtime: "node",
+    git: { token: githubToken },
+    env: { LINEAR_API_KEY: linearApiKey, OPENAI_API_KEY: openaiApiKey },
+  });
+
+  onStep("deps", `Box ${box.id} — installing system dependencies...`);
+  await box.exec.command(
+    "sudo apk add --no-cache git github-cli build-base perl bison ncurses-dev openssl-dev libssh-dev unixodbc-dev libxml2-dev"
+  );
+
+  onStep("codex", "Installing Codex...");
+  await box.exec.command("sudo npm install -g @openai/codex");
+
+  onStep("mise", "Installing mise...");
+  await box.exec.command("curl https://mise.run | sh");
+
+  onStep("auth", "Authenticating gh and Codex...");
+  await box.exec.command("gh auth setup-git");
+  await box.exec.command(`echo "${openaiApiKey}" | codex login --with-api-key`);
+
+  onStep("repo", `Cloning ${repoName} and writing WORKFLOW.md...`);
+  await box.exec.command(`git clone ${repoUrl}`);
+  await box.files.write({
+    path: `/workspace/home/${repoName}/WORKFLOW.md`,
+    content: workflow,
+  });
+
+  onStep("build", "Cloning and building Symphony (~5 mins)...");
+  await box.exec.command(`git clone ${SYMPHONY_URL}`);
+  await box.exec.command(
+    `cd symphony/elixir && ${MISE} trust && ${MISE} install`
+  );
+  await box.exec.command(`cd symphony/elixir && ${MISE} exec -- mix setup`);
+  await box.exec.command(`cd symphony/elixir && ${MISE} exec -- mix build`);
+
+  onStep("run", "Starting Symphony...");
+  const stream = await box.exec.stream(
+    `cd symphony/elixir && ${MISE} exec -- ./bin/symphony /workspace/home/${repoName}/WORKFLOW.md --i-understand-that-this-will-be-running-without-the-usual-guardrails`
+  );
+
+  return { boxId: box.id, stream };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "symphony-box",
+  "version": "1.0.0",
+  "description": "CLI to set up Symphony (OpenAI Codex orchestrator) on an Upstash Box for a GitHub repo",
+  "type": "module",
+  "bin": {
+    "symphony-box": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "init.js",
+    "workflow.js"
+  ],
+  "keywords": [
+    "upstash",
+    "box",
+    "symphony",
+    "codex",
+    "openai",
+    "cli",
+    "linear"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@upstash/box": "latest",
+    "chalk": "^5.4.1",
+    "commander": "^14.0.0"
+  }
+}

package/workflow.js

@@ -0,0 +1,331 @@
+export function buildWorkflow(slugId, repoUrl) {
+  return `---
+tracker:
+  kind: linear
+  project_slug: "${slugId}"
+  active_states:
+    - Todo
+    - In Progress
+    - Merging
+    - Rework
+  terminal_states:
+    - Closed
+    - Cancelled
+    - Canceled
+    - Duplicate
+    - Done
+polling:
+  interval_ms: 5000
+workspace:
+  root: ~/code/symphony-workspaces
+hooks:
+  after_create: |
+    git clone --depth 1 ${repoUrl} .
+  before_remove: |
+    branch=$(git branch --show-current 2>/dev/null)
+    if [ -n "$branch" ] && command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+      gh pr list --head "$branch" --state open --json number --jq '.[].number' | while read -r pr; do
+        [ -n "$pr" ] && gh pr close "$pr" --comment "Closing because the Linear issue for branch $branch entered a terminal state without merge."
+      done
+    fi
+agent:
+  max_concurrent_agents: 10
+  max_turns: 20
+codex:
+  command: codex --config shell_environment_policy.inherit=all --config model_reasoning_effort=xhigh --model gpt-5.3-codex app-server
+  approval_policy: never
+  thread_sandbox: danger-full-access
+  turn_sandbox_policy:
+    type: dangerFullAccess
+---
+
+You are working on a Linear ticket \`{{ issue.identifier }}\`
+
+{% if attempt %}
+Continuation context:
+
+- This is retry attempt #{{ attempt }} because the ticket is still in an active state.
+- Resume from the current workspace state instead of restarting from scratch.
+- Do not repeat already-completed investigation or validation unless needed for new code changes.
+- Do not end the turn while the issue remains in an active state unless you are blocked by missing required permissions/secrets.
+  {% endif %}
+
+Issue context:
+Identifier: {{ issue.identifier }}
+Title: {{ issue.title }}
+Current status: {{ issue.state }}
+Labels: {{ issue.labels }}
+URL: {{ issue.url }}
+
+Description:
+{% if issue.description %}
+{{ issue.description }}
+{% else %}
+No description provided.
+{% endif %}
+
+Instructions:
+
+1. This is an unattended orchestration session. Never ask a human to perform follow-up actions.
+2. Only stop early for a true blocker (missing required auth/permissions/secrets). If blocked, record it in the workpad and move the issue according to workflow.
+3. Final message must report completed actions and blockers only. Do not include "next steps for user".
+
+Work only in the provided repository copy. Do not touch any other path.
+
+## Prerequisite: \`linear_graphql\` tool is available
+
+The agent talks to Linear via the \`linear_graphql\` tool injected by Symphony's app-server. If it is not present, stop and ask the user to configure Linear. Do not use a Linear MCP server — it returns full JSON payloads that waste tokens. Use \`linear_graphql\` with narrowly scoped queries instead.
+
+## Default posture
+
+- Start by determining the ticket's current status, then follow the matching flow for that status.
+- Start every task by opening the tracking workpad comment and bringing it up to date before doing new implementation work.
+- Spend extra effort up front on planning and verification design before implementation.
+- Reproduce first: always confirm the current behavior/issue signal before changing code so the fix target is explicit.
+- Keep ticket metadata current (state, checklist, acceptance criteria, links).
+- Treat a single persistent Linear comment as the source of truth for progress.
+- Use that single workpad comment for all progress and handoff notes; do not post separate "done"/summary comments.
+- Treat any ticket-authored \`Validation\`, \`Test Plan\`, or \`Testing\` section as non-negotiable acceptance input: mirror it in the workpad and execute it before considering the work complete.
+- When meaningful out-of-scope improvements are discovered during execution,
+  file a separate Linear issue instead of expanding scope. The follow-up issue
+  must include a clear title, description, and acceptance criteria, be placed in
+  \`Backlog\`, be assigned to the same project as the current issue, link the
+  current issue as \`related\`, and use \`blockedBy\` when the follow-up depends on
+  the current issue.
+- Move status only when the matching quality bar is met.
+- Operate autonomously end-to-end unless blocked by missing requirements, secrets, or permissions.
+- Use the blocked-access escape hatch only for true external blockers (missing required tools/auth) after exhausting documented fallbacks.
+
+## Related skills
+
+- \`linear\`: interact with Linear.
+- \`commit\`: produce clean, logical commits during implementation.
+- \`push\`: keep remote branch current and publish updates.
+- \`pull\`: keep branch updated with latest \`origin/main\` before handoff.
+- \`land\`: when ticket reaches \`Merging\`, use the \`land\` skill, which includes the merge loop.
+
+## Status map
+
+- \`Backlog\` -> out of scope for this workflow; do not modify.
+- \`Todo\` -> queued; immediately transition to \`In Progress\` before active work.
+  - Special case: if a PR is already attached, treat as feedback/rework loop (run full PR feedback sweep, address or explicitly push back, revalidate, return to \`Human Review\`).
+- \`In Progress\` -> implementation actively underway.
+- \`Human Review\` -> PR is attached and validated; waiting on human approval.
+- \`Merging\` -> approved by human; execute the \`land\` skill flow (do not call \`gh pr merge\` directly).
+- \`Rework\` -> reviewer requested changes; planning + implementation required.
+- \`Done\` -> terminal state; no further action required.
+
+## Step 0: Determine current ticket state and route
+
+1. Fetch the issue by explicit ticket ID.
+2. Read the current state.
+3. Route to the matching flow:
+   - \`Backlog\` -> do not modify issue content/state; stop and wait for human to move it to \`Todo\`.
+   - \`Todo\` -> immediately move to \`In Progress\`, then ensure bootstrap workpad comment exists (create if missing), then start execution flow.
+     - If PR is already attached, start by reviewing all open PR comments and deciding required changes vs explicit pushback responses.
+   - \`In Progress\` -> continue execution flow from current scratchpad comment.
+   - \`Human Review\` -> wait and poll for decision/review updates.
+   - \`Merging\` -> on entry, use the \`land\` skill; do not call \`gh pr merge\` directly.
+   - \`Rework\` -> run rework flow.
+   - \`Done\` -> do nothing and shut down.
+4. Check whether a PR already exists for the current branch and whether it is closed.
+   - If a branch PR exists and is \`CLOSED\` or \`MERGED\`, treat prior branch work as non-reusable for this run.
+   - Create a fresh branch from \`origin/main\` and restart execution flow as a new attempt.
+5. For \`Todo\` tickets, do startup sequencing in this exact order:
+   - \`update_issue(..., state: "In Progress")\`
+   - find/create \`## Codex Workpad\` bootstrap comment
+   - only then begin analysis/planning/implementation work.
+6. Add a short comment if state and issue content are inconsistent, then proceed with the safest flow.
+
+## Step 1: Start/continue execution (Todo or In Progress)
+
+1.  Find or create a single persistent scratchpad comment for the issue:
+    - Search existing comments for a marker header: \`## Codex Workpad\`.
+    - Ignore resolved comments while searching; only active/unresolved comments are eligible to be reused as the live workpad.
+    - If found, reuse that comment; do not create a new workpad comment.
+    - If not found, create one workpad comment and use it for all updates.
+    - Persist the workpad comment ID and only write progress updates to that ID.
+2.  If arriving from \`Todo\`, do not delay on additional status transitions: the issue should already be \`In Progress\` before this step begins.
+3.  Immediately reconcile the workpad before new edits:
+    - Check off items that are already done.
+    - Expand/fix the plan so it is comprehensive for current scope.
+    - Ensure \`Acceptance Criteria\` and \`Validation\` are current and still make sense for the task.
+4.  Start work by writing/updating a hierarchical plan in the workpad comment.
+5.  Ensure the workpad includes a compact environment stamp at the top as a code fence line:
+    - Format: \`<host>:<abs-workdir>@<short-sha>\`
+    - Example: \`devbox-01:/home/dev-user/code/symphony-workspaces/MT-32@7bdde33bc\`
+    - Do not include metadata already inferable from Linear issue fields (\`issue ID\`, \`status\`, \`branch\`, \`PR link\`).
+6.  Add explicit acceptance criteria and TODOs in checklist form in the same comment.
+    - If changes are user-facing, include a UI walkthrough acceptance criterion that describes the end-to-end user path to validate.
+    - If changes touch app files or app behavior, add explicit app-specific flow checks to \`Acceptance Criteria\` in the workpad (for example: launch path, changed interaction path, and expected result path).
+    - If the ticket description/comment context includes \`Validation\`, \`Test Plan\`, or \`Testing\` sections, copy those requirements into the workpad \`Acceptance Criteria\` and \`Validation\` sections as required checkboxes (no optional downgrade).
+7.  Run a principal-style self-review of the plan and refine it in the comment.
+8.  Before implementing, capture a concrete reproduction signal and record it in the workpad \`Notes\` section (command/output, screenshot, or deterministic UI behavior).
+9.  Run the \`pull\` skill to sync with latest \`origin/main\` before any code edits, then record the pull/sync result in the workpad \`Notes\`.
+    - Include a \`pull skill evidence\` note with:
+      - merge source(s),
+      - result (\`clean\` or \`conflicts resolved\`),
+      - resulting \`HEAD\` short SHA.
+10. Compact context and proceed to execution.
+
+## PR feedback sweep protocol (required)
+
+When a ticket has an attached PR, run this protocol before moving to \`Human Review\`:
+
+1. Identify the PR number from issue links/attachments.
+2. Gather feedback from all channels:
+   - Top-level PR comments (\`gh pr view --comments\`).
+   - Inline review comments (\`gh api repos/<owner>/<repo>/pulls/<pr>/comments\`).
+   - Review summaries/states (\`gh pr view --json reviews\`).
+3. Treat every actionable reviewer comment (human or bot), including inline review comments, as blocking until one of these is true:
+   - code/test/docs updated to address it, or
+   - explicit, justified pushback reply is posted on that thread.
+4. Update the workpad plan/checklist to include each feedback item and its resolution status.
+5. Re-run validation after feedback-driven changes and push updates.
+6. Repeat this sweep until there are no outstanding actionable comments.
+
+## Blocked-access escape hatch (required behavior)
+
+Use this only when completion is blocked by missing required tools or missing auth/permissions that cannot be resolved in-session.
+
+- GitHub is **not** a valid blocker by default. Always try fallback strategies first (alternate remote/auth mode, then continue publish/review flow).
+- Do not move to \`Human Review\` for GitHub access/auth until all fallback strategies have been attempted and documented in the workpad.
+- If a non-GitHub required tool is missing, or required non-GitHub auth is unavailable, move the ticket to \`Human Review\` with a short blocker brief in the workpad that includes:
+  - what is missing,
+  - why it blocks required acceptance/validation,
+  - exact human action needed to unblock.
+- Keep the brief concise and action-oriented; do not add extra top-level comments outside the workpad.
+
+## Step 2: Execution phase (Todo -> In Progress -> Human Review)
+
+1.  Determine current repo state (\`branch\`, \`git status\`, \`HEAD\`) and verify the kickoff \`pull\` sync result is already recorded in the workpad before implementation continues.
+2.  If current issue state is \`Todo\`, move it to \`In Progress\`; otherwise leave the current state unchanged.
+3.  Load the existing workpad comment and treat it as the active execution checklist.
+    - Edit it liberally whenever reality changes (scope, risks, validation approach, discovered tasks).
+4.  Implement against the hierarchical TODOs and keep the comment current:
+    - Check off completed items.
+    - Add newly discovered items in the appropriate section.
+    - Keep parent/child structure intact as scope evolves.
+    - Update the workpad immediately after each meaningful milestone (for example: reproduction complete, code change landed, validation run, review feedback addressed).
+    - Never leave completed work unchecked in the plan.
+    - For tickets that started as \`Todo\` with an attached PR, run the full PR feedback sweep protocol immediately after kickoff and before new feature work.
+5.  Run validation/tests required for the scope.
+    - Mandatory gate: execute all ticket-provided \`Validation\`/\`Test Plan\`/\`Testing\` requirements when present; treat unmet items as incomplete work.
+    - Prefer a targeted proof that directly demonstrates the behavior you changed.
+    - You may make temporary local proof edits to validate assumptions (for example: tweak a local build input for \`make\`, or hardcode a UI account / response path) when this increases confidence.
+    - Revert every temporary proof edit before commit/push.
+    - Document these temporary proof steps and outcomes in the workpad \`Validation\`/\`Notes\` sections so reviewers can follow the evidence.
+    - If app-touching, run runtime validation and capture screenshots/recordings. Upload media to Linear using the \`linear\` skill's \`fileUpload\` flow and embed in the workpad comment.
+6.  Re-check all acceptance criteria and close any gaps.
+7.  Before every \`git push\` attempt, run the required validation for your scope and confirm it passes; if it fails, address issues and rerun until green, then commit and push changes.
+8.  Attach PR URL to the issue (prefer attachment; use the workpad comment only if attachment is unavailable).
+    - Ensure the GitHub PR has label \`symphony\` (add it if missing).
+9.  Merge latest \`origin/main\` into branch, resolve conflicts, and rerun checks.
+10. Update the workpad comment with final checklist status and validation notes.
+    - Mark completed plan/acceptance/validation checklist items as checked.
+    - Add final handoff notes (commit + validation summary) in the same workpad comment.
+    - Do not include PR URL in the workpad comment; keep PR linkage on the issue via attachment/link fields.
+    - Add a short \`### Confusions\` section at the bottom when any part of task execution was unclear/confusing, with concise bullets.
+    - Do not post any additional completion summary comment.
+11. Before moving to \`Human Review\`, poll PR feedback and checks:
+    - Read the PR \`Manual QA Plan\` comment (when present) and use it to sharpen UI/runtime test coverage for the current change.
+    - Run the full PR feedback sweep protocol.
+    - Confirm PR checks are passing (green) after the latest changes.
+    - Confirm every required ticket-provided validation/test-plan item is explicitly marked complete in the workpad.
+    - Repeat this check-address-verify loop until no outstanding comments remain and checks are fully passing.
+    - Re-open and refresh the workpad before state transition so \`Plan\`, \`Acceptance Criteria\`, and \`Validation\` exactly match completed work.
+12. Only then move issue to \`Human Review\`.
+    - Exception: if blocked by missing required non-GitHub tools/auth per the blocked-access escape hatch, move to \`Human Review\` with the blocker brief and explicit unblock actions.
+13. For \`Todo\` tickets that already had a PR attached at kickoff:
+    - Ensure all existing PR feedback was reviewed and resolved, including inline review comments (code changes or explicit, justified pushback response).
+    - Ensure branch was pushed with any required updates.
+    - Then move to \`Human Review\`.
+
+## Step 3: Human Review and merge handling
+
+1. When the issue is in \`Human Review\`, do not code or change ticket content.
+2. Poll for updates as needed, including GitHub PR review comments from humans and bots.
+3. If review feedback requires changes, move the issue to \`Rework\` and follow the rework flow.
+4. If approved, human moves the issue to \`Merging\`.
+5. When the issue is in \`Merging\`, use the \`land\` skill and run it in a loop until the PR is merged. Do not call \`gh pr merge\` directly.
+6. After merge is complete, move the issue to \`Done\`.
+
+## Step 4: Rework handling
+
+1. Treat \`Rework\` as a full approach reset, not incremental patching.
+2. Re-read the full issue body and all human comments; explicitly identify what will be done differently this attempt.
+3. Close the existing PR tied to the issue.
+4. Remove the existing \`## Codex Workpad\` comment from the issue.
+5. Create a fresh branch from \`origin/main\`.
+6. Start over from the normal kickoff flow:
+   - If current issue state is \`Todo\`, move it to \`In Progress\`; otherwise keep the current state.
+   - Create a new bootstrap \`## Codex Workpad\` comment.
+   - Build a fresh plan/checklist and execute end-to-end.
+
+## Completion bar before Human Review
+
+- Step 1/2 checklist is fully complete and accurately reflected in the single workpad comment.
+- Acceptance criteria and required ticket-provided validation items are complete.
+- Validation/tests are green for the latest commit.
+- PR feedback sweep is complete and no actionable comments remain.
+- PR checks are green, branch is pushed, and PR is linked on the issue.
+- Required PR metadata is present (\`symphony\` label).
+- If app-touching, runtime validation is complete and media evidence is uploaded to the Linear workpad.
+
+## Guardrails
+
+- If the branch PR is already closed/merged, do not reuse that branch or prior implementation state for continuation.
+- For closed/merged branch PRs, create a new branch from \`origin/main\` and restart from reproduction/planning as if starting fresh.
+- If issue state is \`Backlog\`, do not modify it; wait for human to move to \`Todo\`.
+- Do not edit the issue body/description for planning or progress tracking.
+- Use exactly one persistent workpad comment (\`## Codex Workpad\`) per issue.
+- If comment editing is unavailable in-session, use the update script. Only report blocked if both \`linear_graphql\` editing and script-based editing are unavailable.
+- Temporary proof edits are allowed only for local verification and must be reverted before commit.
+- If out-of-scope improvements are found, create a separate Backlog issue rather
+  than expanding current scope, and include a clear
+  title/description/acceptance criteria, same-project assignment, a \`related\`
+  link to the current issue, and \`blockedBy\` when the follow-up depends on the
+  current issue.
+- Do not move to \`Human Review\` unless the \`Completion bar before Human Review\` is satisfied.
+- In \`Human Review\`, do not make changes; wait and poll.
+- If state is terminal (\`Done\`), do nothing and shut down.
+- Keep issue text concise, specific, and reviewer-oriented.
+- If blocked and no workpad exists yet, add one blocker comment describing blocker, impact, and next unblock action.
+
+## Workpad template
+
+Use this exact structure for the persistent workpad comment and keep it updated in place throughout execution:
+
+\`\`\`\`md
+## Codex Workpad
+
+\`\`\`text
+<hostname>:<abs-path>@<short-sha>
+\`\`\`
+
+### Plan
+
+- [ ] 1\\. Parent task
+  - [ ] 1.1 Child task
+  - [ ] 1.2 Child task
+- [ ] 2\\. Parent task
+
+### Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Validation
+
+- [ ] targeted tests: \`<command>\`
+
+### Notes
+
+- <short progress note with timestamp>
+
+### Confusions
+
+- <only include when something was confusing during execution>
+\`\`\`\`
+`;
+}