{"record":{"id":"7e3cc751ebb0a236","repo":"coleam00/Archon","slug":"workflow-workflow-name-sets-worktree-enabled","errorCode":null,"errorMessage":"Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n  --branch requires an isolated worktree.\n  Drop --branch or change the workflow's worktree.enabled.","messagePattern":"Workflow '(.+?)' sets worktree\\.enabled: false \\(runs in live checkout\\)\\.\n  --branch requires an isolated worktree\\.\n  Drop --branch or change the workflow's worktree\\.enabled\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/workflow.ts","lineNumber":1891,"sourceCode":"  }\n\n  // Per-dispatch --base override, normalized once. Wins over repo config + the\n  // codebase default for both the worktree cut-from (the provider request's\n  // `baseOverride` below) and the PR target / $BASE_BRANCH (executeWorkflow's\n  // `baseOverride` opt). Both halves need their own channel: the `baseBranch`\n  // field on either side is the codebase-default FALLBACK and ranks below repo\n  // config, so routing the flag through it would silently lose to a repo that\n  // sets `worktree.baseBranch`.\n  const flagBase = options.baseBranch?.trim() || undefined;\n\n  // Reconcile workflow-level worktree policy with invocation flags.\n  // The workflow YAML's `worktree.enabled` pins isolation regardless of caller —\n  // a mismatch between policy and flags is a user error we surface loudly\n  // rather than silently applying one side and ignoring the other.\n  const pinnedEnabled = workflow.worktree?.enabled;\n  if (pinnedEnabled === false) {\n    if (options.branchName !== undefined) {\n      throw new Error(\n        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\\n` +\n          '  --branch requires an isolated worktree.\\n' +\n          \"  Drop --branch or change the workflow's worktree.enabled.\"\n      );\n    }\n    if (options.fromBranch !== undefined) {\n      throw new Error(\n        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\\n` +\n          '  --from/--from-branch only applies when a worktree is created.\\n' +\n          \"  Drop --from or change the workflow's worktree.enabled.\"\n      );\n    }\n    if (options.baseBranch !== undefined) {\n      throw new Error(\n        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\\n` +\n          '  --base only applies when a worktree is created.\\n' +\n          \"  Drop --base or change the workflow's worktree.enabled.\"\n      );","sourceCodeStart":1873,"sourceCodeEnd":1909,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/workflow.ts#L1873-L1909","documentation":"A workflow whose YAML pins `worktree.enabled: false` always runs in the live checkout. Passing `--branch` — which names the branch of an isolated worktree — would be silently ignored, so the CLI rejects the mismatch between the workflow's isolation policy and the caller's flag rather than applying one side.","triggerScenarios":"`archon workflow start <workflow-with-worktree-enabled-false> --branch <name>` — options.branchName set while workflow.worktree.enabled === false.","commonSituations":"Reusing a shared `--branch` wrapper script across workflows; not realizing the target workflow's YAML disables worktree isolation.","solutions":["Drop the `--branch` flag when starting this workflow.","Change the workflow YAML to `worktree.enabled: true` if runs should be isolated and branch-controlled."],"exampleFix":"// before\narchon workflow start live-sync --branch fix/thing\n// after\narchon workflow start live-sync","handlingStrategy":"validation","validationCode":"// check the workflow's pinned policy before passing lane flags\nconst wf = JSON.parse(await Bun.file(`.archon/workflows/${name}.yaml`).text()); // or via `archon workflow show`\nif (wf.worktree?.enabled === false && args.includes('--branch')) {\n  throw new Error(`${name} runs in the live checkout; --branch is not applicable.`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Inspect `worktree.enabled` in the workflow YAML before adding isolation flags.","Keep per-workflow launch scripts instead of one shared flag set."],"tags":["cli","flag-conflict","worktree","workflow-config"],"backgroundTag":"flag-vs-workflow-policy-conflict","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}