Add quest startup branch preparation

.ai/allowlist.json

@@ -28,6 +28,11 @@
     "code-reviewer-b": "gpt-5.4",
     "fixer": "gpt-5.4"
   },
+  "quest_startup": {
+    "branch_mode": "branch",
+    "branch_prefix": "quest/",
+    "worktree_root": ".worktrees/quest"
+  },
   "review_mode": "full",
   "fast_review_thresholds": {
     "max_files": 5,

.ai/schemas/allowlist.schema.json

@@ -37,6 +37,17 @@
       },
       "additionalProperties": { "type": "string" }
     },
+    "quest_startup": {
+      "type": "object",
+      "properties": {
+        "branch_mode": {
+          "type": "string",
+          "enum": ["branch", "worktree", "none"]
+        },
+        "branch_prefix": { "type": "string" },
+        "worktree_root": { "type": "string" }
+      }
+    },
     "review_mode": { "type": "string", "enum": ["auto", "fast", "full"] },
     "fast_review_thresholds": {
       "type": "object",

.gitignore

@@ -1,5 +1,6 @@
 # Quest ephemeral state
 .quest/
+.worktrees/
 
 # Workspace scratch
 .ws/

.quest-checksums

@@ -6,7 +6,7 @@
 8501266cd7b1f0004361aec200d85f02f35b1de2bc57648fe03625867b1c46e3  .agents/skills/README.md
 c5cbf7daca607003d8904c1d97fc45fc4a0f3eb9f089c43457d33a1d9aac3f98  .ai/quest.md
 a17dbe2d7bfb6cdddde81b7b4fdec27083b9ee81db32c45a9644d4f9ebd2ca15  .ai/roles/quest_agent.md
-fe83cda3c43c2562ed5a5ebc1bf7c227caca7f041987e5b1d3d5eb4cc0f9943f  .ai/schemas/allowlist.schema.json
+cbcc84c5e116dc0f9bc6764d427ee291e399e4b9c6ec284d5c9479728e31b75b  .ai/schemas/allowlist.schema.json
 49eb6396d1c1cbdf232ed1a14aedbb7ef2ee99534c52dbc6ca4acd6e63da3770  .ai/schemas/handoff.schema.json
 ba648315fd083c7cfec66b66fc2fe97fbe53dbe95904789ab371ea667159a89b  .ai/templates/plan.md
 0c2681a3d0ae6ae88ae3361dd6e8ad0ab8ea3360f6984d5a982790660b8f13ce  .ai/templates/pr_description.md
@@ -52,8 +52,8 @@ c1ece37ca71c80ba1880631ac2762a79999b3812be243dd9a249a10065e3aab7  .skills/quest/
 e1cef5bb261421226a8007f88aab5cac0295b16f4044735856305c155a952376  .skills/quest/agents/README.md
 5e838b78b482e1c4933593dd57d7702ab03f5d3f2d10a062db5489ef184c9c88  .skills/quest/delegation/questioner.md
 c1138ae5c661af4333e465910dd864aa7d1c3a253f8696bfbcd2e679f5cf5801  .skills/quest/delegation/router.md
-5d32a6474a635fc0e9ba14dd92ca3852c0b6fd050494b624546d27c1675fedf0  .skills/quest/delegation/workflow.md
-75a7d855a0d5cad4f2ef0f0b7675ee6de550b8b53104e3968db7e66d477fef83  .skills/quest/SKILL.md
+a84c771b6837f2112652c4754aa410e647b1fcc4e33875c1a93539c06d2bd06a  .skills/quest/delegation/workflow.md
+75a1c7edec4aaaf443c2e8c75435a1ce65481d9035fbdc2a162c6fac6775b63c  .skills/quest/SKILL.md
 05689231eed6eae8df6fc429b909690218806222af2181c7689ee7bcd6184fbd  .skills/README.md
 70a8d9bb6e2de003e2a47e51028ec7d3c1ffb3fa76a36aa1fb5cff7835c47118  .skills/SKILLS.md
 63cd28a52d17218959af1e81707aa289b58b1ba8bfc09b0f009aa24cb33d23df  scripts/quest_celebrate/__init__.py
@@ -66,6 +66,7 @@ c594d592326fbe99f38e9dbd784b1926f7067c00784cdaede50f57f6c8dbb1e5  scripts/quest_
 2882f437fcb5cae46d598360d78b5bb096299f0aab66fc75d7ce514feada834e  scripts/quest_celebrate/terminal.py
 f662acec6363dd22b02f504e349e0d53c57293ffb422f371540b3e5b7620f9a7  scripts/quest_installer.sh
 dff199c72aea3b7157492c60eaced28848b012bd2d21ff3222f935a4dfaf8b85  scripts/validate-handoff-contracts.sh
-c609bc6014f0d1980a8a203dc05b6ab2db4f7a3e5104d2c2a0191da78229a697  scripts/validate-manifest.sh
-85274507a2928a68c2f2a14c4c1a6ff7f2b17b5f9910e620d753113b73c855ab  scripts/validate-quest-config.sh
+c73acc52afed8510a3c5d1d4338b0c5c3315b335395c727a721404ce22a404cb  scripts/validate-manifest.sh
+d2b32057859a23cfb90a4bf6e801f6d95354c09d8c1fe8235666bebfab9fcc8c  scripts/validate-quest-config.sh
+96190d1c933df39145c6246abacc328619fb99e699d54f97288e191703174d0b  scripts/quest_startup_branch.py
 fbd4a93c3cacfb2feae00fc7a8d1e4bacb05992eb81545626bbf7a4c8057850c  scripts/validate-quest-state.sh

.quest-manifest

@@ -71,6 +71,7 @@ scripts/validate-handoff-contracts.sh
 scripts/claude_cli_bridge.py
 scripts/quest_claude_probe.py
 scripts/quest_claude_runner.py
+scripts/quest_startup_branch.py
 scripts/quest_checks/__init__.py
 scripts/quest_checks/cli.py
 scripts/quest_runtime/__init__.py

.skills/quest/SKILL.md

@@ -160,25 +160,42 @@ Before creating the quest folder, present the routing classification to the user
 ### Quest Folder Creation
 
 1. Generate a slug (lowercase, hyphenated, 2-5 words) and inform the user
-2. Create `.quest/<slug>_YYYY-MM-DD__HHMM/` with subfolders:
+2. Run quest startup branch preparation before creating the quest folder:
+   - Execute: `python3 scripts/quest_startup_branch.py --slug <slug>`
+   - Parse the JSON result
+   - If `status` is `"blocked"`: show the returned `message`, do NOT create the quest folder yet, and stop for the user to resolve the git state or config
+   - If `status` is `"created"` or `"skipped"`: continue and surface the returned `message` to the user
+   - Record these fields for `state.json` initialization:
+     - `branch`
+     - `branch_mode`
+     - `worktree_path` (if present)
+   - Behavior rules:
+     - Default mode comes from `.ai/allowlist.json` → `quest_startup.branch_mode` and defaults to `"branch"`
+     - When starting on the repo default branch, Quest creates either a feature branch or a worktree-backed branch from that default branch
+     - When already on a non-default branch, Quest does not create another branch/worktree and records the existing branch for the run
+3. Create `.quest/<slug>_YYYY-MM-DD__HHMM/` with subfolders:
    `phase_01_plan/`, `phase_02_implementation/`, `phase_03_review/`, `logs/`
-3. Write quest brief to `.quest/<id>/quest_brief.md` including:
+4. Write quest brief to `.quest/<id>/quest_brief.md` including:
    - User input (original prompt)
    - Questioner summary (if questioning occurred)
    - **Router classification JSON** (the final routing decision that sent the quest to workflow). This is the classification produced by the most recent router evaluation — if the router ran twice (once before questioning, once after), record the second (final) classification.
-4. Copy `.ai/allowlist.json` to `.quest/<id>/logs/allowlist_snapshot.json`
-5. Initialize `state.json`:
+5. Copy `.ai/allowlist.json` to `.quest/<id>/logs/allowlist_snapshot.json`
+6. Initialize `state.json`:
    ```json
    {
      "quest_id": "<id>",
      "slug": "<slug>",
      "phase": "plan",
      "status": "pending",
      "quest_mode": "workflow",
+     "branch": "quest/<slug> or current branch",
+     "branch_mode": "branch | worktree | none",
+     "worktree_path": "/absolute/path/to/worktree (worktree mode only)",
      "plan_iteration": 0,
      "fix_iteration": 0,
      "created_at": "<timestamp>",
      "updated_at": "<timestamp>"
    }
    ```
    Set `quest_mode` to the user's final selection: `"workflow"` (default) or `"solo"`. This field is read by `workflow.md` to determine agent dispatch and by `validate-quest-state.sh` for artifact checks.
+   `branch_mode` records the actual startup mode used for this quest run after no-op handling. If Quest starts on an existing feature branch, set `branch_mode` to `"none"` and record that branch in `branch`.

.skills/quest/delegation/workflow.md

@@ -258,7 +258,16 @@ This workflow expects to be invoked with a quest brief already prepared.
 
 1. Verify `.quest/<id>/quest_brief.md` exists
 2. If it does not exist, STOP and report error: "Quest brief not found. The routing layer should have created it before invoking workflow."
-3. If it exists, proceed to Step 2
+3. Read `.quest/<id>/state.json` and determine the source workspace root for code-bearing phases:
+   - If `worktree_path` exists and the directory is present, set `source_workspace_root = worktree_path`
+   - Otherwise set `source_workspace_root = <repo root>`
+   - All source edits plus `git status`, `git diff`, and `git log` commands in Steps 4-7 MUST run from `source_workspace_root`
+   - Quest artifacts always remain under `.quest/<id>/` in the original repo root; when `source_workspace_root != <repo root>`, prefer absolute quest artifact paths when invoking builder, reviewers, and fixer
+4. Verify branch context:
+   - If `branch` exists in state.json and `branch_mode == "branch"`, compare it to `git branch --show-current` in `source_workspace_root`
+   - If `branch_mode == "worktree"`, verify the directory at `worktree_path` still exists
+   - If verification fails, warn the user but do not block automatically; they may have switched context intentionally
+5. If the checks pass, proceed to Step 2
 
 ### Step 2: Route Intent
 
@@ -598,6 +607,7 @@ After plan approval, present the plan interactively before proceeding to build.
    - Read `models.builder` from allowlist.
    - If builder model is Codex, invoke via `mcp__codex__codex` with `sandbox_permissions: "workspace-write"`.
    - If builder model is Claude, invoke through Claude runtime (native `Task(...)` when available, bridge in Codex-led sessions).
+   - Run the builder from `source_workspace_root`. If this quest uses a separate worktree, source changes happen there while `.quest/<id>/...` artifacts still point at the original repo root.
    - **Artifact preparation** (per Handoff File Polling §5): Resolve and prepare `pr_description.md`, `builder_feedback_discussion.md`, and `handoff.json` in `.quest/<id>/phase_02_implementation/`.
    - Prompt: Reference file paths only, do not embed content:
      - Approved plan: `.quest/<id>/phase_01_plan/plan.md`
@@ -642,7 +652,7 @@ After plan approval, present the plan interactively before proceeding to build.
 
 
 3. **Build a change summary for Codex:**
-   - Compute from git (the canonical source for what changed):
+   - Compute from git in `source_workspace_root` (the canonical source for what changed):
      - File list: `git diff --name-only`
      - Diff stats: `git diff --stat`
      - LOC totals: `git diff --numstat` and sum added + deleted.
@@ -842,6 +852,7 @@ After plan approval, present the plan interactively before proceeding to build.
    - Read `models.fixer` from allowlist.
    - If fixer model is Codex, invoke via `mcp__codex__codex` with `sandbox_permissions: "workspace-write"`.
    - If fixer model is Claude, invoke through Claude runtime (native `Task(...)` when available, bridge in Codex-led sessions).
+   - Run the fixer from `source_workspace_root`. If this quest uses a separate worktree, source fixes happen there while `.quest/<id>/...` artifacts remain in the original repo root.
    - Prompt: Reference file paths only, do not embed content:
      - Code review A: `.quest/<id>/phase_03_review/review_code-reviewer-a.md`
      - Code review B: `.quest/<id>/phase_03_review/review_code-reviewer-b.md`
@@ -911,11 +922,12 @@ After plan approval, present the plan interactively before proceeding to build.
 
 4. **Show summary** (before archiving — quest directory still exists):
     - Quest ID
-    - Files changed (from `git diff --name-only` and `state.json` artifact paths)
+    - Files changed (from `git diff --name-only` in `source_workspace_root` and `state.json` artifact paths)
     - Total iterations (plan + fix, from `state.json`)
     - Parallel execution stats (read from `.quest/<id>/logs/parallelism.log` if it exists — show each line)
     - Location of artifacts (will be archived to `.quest/archive/<id>/`)
     - Location of journal entry (will be created next)
+    - If `branch_mode == "worktree"` and `worktree_path` exists, remind the user that the implementation branch lives in that worktree and cleanup is manual via `git worktree remove <worktree_path>`
 
 6. **Context health report:**
    If `.quest/<id>/logs/context_health.log` exists, display it in full:
@@ -1096,6 +1108,9 @@ If a Claude role returns `STATUS: needs_human`:
   "slug": "feature-x",
   "phase": "plan | plan_reviewed | presenting | presentation_complete | building | reviewing | fixing | complete",
   "status": "pending | in_progress | complete | blocked",
+  "branch": "quest/feature-x",
+  "branch_mode": "branch | worktree | none",
+  "worktree_path": "/absolute/path/to/worktree or null",
   "plan_iteration": 2,
   "fix_iteration": 0,
   "last_role": "arbiter_agent",

scripts/README.md

@@ -13,6 +13,7 @@ Build and utility scripts for the Quest repository.
 | `quest_preflight.sh` | Checks second-model readiness before quest routing. Codex-led Claude probes now retain a recent successful host probe under `.quest/cache/` so later quest starts can reuse it. |
 | `quest_claude_probe.py` | Probes the Claude bridge by requiring a real artifact write and `handoff.json` under the quest logs directory. |
 | `quest_state.py` | Updates `.quest/<id>/state.json` consistently and refreshes `updated_at`. |
+| `quest_startup_branch.py` | Creates the startup branch or worktree for a new quest from `.ai/allowlist.json` and returns machine-readable branch context JSON. |
 | `quest_claude_runner.py` | Runs Claude-designated Quest roles through the additive Codex-host Claude adapter, using `scripts/claude_cli_bridge.py` as transport plus `bypassPermissions`, explicit `--add-dir` access, handoff polling, and `context_health.log` updates. Native Claude-led Quest behavior stays on `Task(...)`. |
 | `quest_installer.sh` | Installs and updates Quest in any repository. Handles fresh installs, updates, and checksum-based change detection. |
 | `validate-quest-config.sh` | Validates quest configuration files (allowlist JSON schema, role markdown completeness). Used by pre-commit hooks and CI. |
@@ -28,6 +29,9 @@ python3 scripts/quest_dashboard/build_quest_dashboard.py
 # Update quest state without hand-editing JSON
 python3 scripts/quest_state.py --quest-dir .quest/<id> --phase plan_reviewed --status complete
 
+# Prepare startup branch/worktree context for a new quest
+python3 scripts/quest_startup_branch.py --slug feature-x
+
 # Run a Claude-designated role via the local bridge with file polling
 python3 scripts/quest_claude_runner.py --quest-dir .quest/<id> --phase plan_review --agent plan-reviewer-a --iter 1 --prompt-file .quest/<id>/phase_01_plan/reviewer_a_prompt.txt --handoff-file .quest/<id>/phase_01_plan/handoff_plan-reviewer-a.json