sequant 2.3.0 → 2.5.0

package/dist/src/lib/workflow/phase-executor.js

@@ -13,77 +13,21 @@ import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
 import { ApiError } from "../errors.js";
+import { phaseRegistry } from "./phase-registry.js";
+import { bracketedConsoleLog } from "./notice.js";
 /**
- * Natural language prompts for each phase.
- * Claude Code invokes the corresponding skills via natural language.
- */
-const PHASE_PROMPTS = {
-    spec: "Review GitHub issue #{issue} and create an implementation plan with verification criteria. Run the /spec {issue} workflow.",
-    "security-review": "Perform a deep security analysis for GitHub issue #{issue} focusing on auth, permissions, and sensitive operations. Run the /security-review {issue} workflow.",
-    testgen: "Generate test stubs for GitHub issue #{issue} based on the specification. Run the /testgen {issue} workflow.",
-    exec: "Implement the feature for GitHub issue #{issue} following the spec. Run the /exec {issue} workflow.",
-    test: "Execute structured browser-based testing for GitHub issue #{issue}. Run the /test {issue} workflow.",
-    verify: "Verify the implementation for GitHub issue #{issue} by running commands and capturing output. Run the /verify {issue} workflow.",
-    qa: "Review the implementation for GitHub issue #{issue} against acceptance criteria. Run the /qa {issue} workflow.",
-    loop: "Parse test/QA findings for GitHub issue #{issue} and iterate until quality gates pass. Run the /loop {issue} workflow.",
-    merger: "Integrate and merge completed worktrees for GitHub issue #{issue}. Run the /merger {issue} workflow.",
-};
-/**
- * Self-contained prompts for non-Claude agents (Aider, Codex, etc.).
- * These agents don't have a skill system, so prompts must include
- * full instructions rather than skill invocations.
- */
-const AIDER_PHASE_PROMPTS = {
-    spec: `Read GitHub issue #{issue} using 'gh issue view #{issue}'.
-Create a spec comment on the issue with:
-1. Implementation plan
-2. Acceptance criteria as a checklist
-3. Risk assessment
-Post the comment using 'gh issue comment #{issue} --body "<comment>"'.`,
-    "security-review": `Perform a security review for GitHub issue #{issue}.
-Read the issue with 'gh issue view #{issue}'.
-Check for auth, permissions, injection, and sensitive data issues.
-Post findings as a comment on the issue.`,
-    testgen: `Generate test stubs for GitHub issue #{issue}.
-Read the spec comments on the issue with 'gh issue view #{issue} --comments'.
-Create test files with describe/it blocks covering the acceptance criteria.
-Use the project's existing test framework.`,
-    exec: `Implement the feature described in GitHub issue #{issue}.
-Read the issue and any spec comments with 'gh issue view #{issue} --comments'.
-Follow the implementation plan from the spec.
-Write tests for new functionality.
-Ensure the build passes with 'npm test' and 'npm run build'.`,
-    test: `Test the implementation for GitHub issue #{issue}.
-Run 'npm test' and verify all tests pass.
-Check for edge cases and error handling.`,
-    verify: `Verify the implementation for GitHub issue #{issue}.
-Run relevant commands and capture their output for review.`,
-    qa: `Review the changes for GitHub issue #{issue}.
-Run 'npm test' and 'npm run build' to verify everything works.
-Check each acceptance criterion from the issue comments.
-Output a verdict: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, or AC_NOT_MET
-with format "### Verdict: <VERDICT>" followed by an explanation.`,
-    loop: `Review test and QA findings for GitHub issue #{issue}.
-Fix any issues identified in the QA feedback.
-Re-run 'npm test' and 'npm run build' until all quality gates pass.`,
-    merger: `Integrate and merge completed worktrees for GitHub issue #{issue}.
-Ensure all branches are up to date and merge cleanly.`,
-};
-/**
- * Phases that require worktree isolation.
- * Only `spec` runs in the main repo (planning-only, no file changes).
- * All other phases must run in the worktree because:
- * 1. They need to read/modify the worktree code
- * 2. Resuming a session created in a different cwd crashes the SDK
+ * Determine whether a phase's session must run inside the issue worktree.
+ *
+ * Sourced from `phaseRegistry.get(phase).requiresWorktree` — replaces the
+ * previous hardcoded `ISOLATED_PHASES` array. Phases must:
+ * 1. Read/modify worktree code
+ * 2. Resume a session from the same cwd it was created in (SDK constraint)
  */
-const ISOLATED_PHASES = [
-    "exec",
-    "security-review",
-    "testgen",
-    "test",
-    "qa",
-    "loop",
-];
+function phaseRequiresWorktree(phase) {
+    return phaseRegistry.has(phase)
+        ? phaseRegistry.get(phase).requiresWorktree
+        : false;
+}
 /**
  * Cold-start retry threshold in seconds.
  * Failures under this duration are likely Claude Code subprocess initialization
@@ -137,15 +81,23 @@ export function createThrottledReporter(fn, intervalMs) {
     return { report, cancel };
 }
 /**
- * Spec-specific retry configuration.
+ * Spec-specific retry configuration. Sourced from the phase registry's
+ * `retryStrategy` field — `phase-registry.ts` is the source of truth.
+ *
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
  * transient GitHub API issues and rate limits. One extra retry with backoff
  * recovers most of these without user intervention.
+ *
+ * Fallback literals (5000 / 1) match the legacy hardcoded values and only
+ * fire if the spec registration is removed or its `retryStrategy` is unset,
+ * which would be a misconfiguration. Tests pin these at 5000 / 1, so any
+ * drift surfaces immediately.
  */
+const SPEC_RETRY_STRATEGY = phaseRegistry.get("spec").retryStrategy;
 /** @internal Exported for testing only */
-export const SPEC_RETRY_BACKOFF_MS = 5000;
+export const SPEC_RETRY_BACKOFF_MS = SPEC_RETRY_STRATEGY?.backoffMs ?? 5000;
 /** @internal Exported for testing only */
-export const SPEC_EXTRA_RETRIES = 1;
+export const SPEC_EXTRA_RETRIES = SPEC_RETRY_STRATEGY?.extraRetries ?? 1;
 export function parseQaVerdict(output) {
     if (!output)
         return null;
@@ -154,8 +106,16 @@ export function parseQaVerdict(output) {
     // - "**Verdict:** X" (bold label with colon inside)
     // - "**Verdict:** **X**" (bold label and bold value)
     // - "Verdict: X" (plain)
-    // Case insensitive, handles optional markdown formatting
-    const verdictMatch = output.match(/(?:###?\s*)?(?:\*\*)?Verdict:?\*?\*?\s*\*?\*?\s*(READY_FOR_MERGE|AC_MET_BUT_NOT_A_PLUS|AC_NOT_MET|NEEDS_VERIFICATION)\*?\*?/i);
+    // - "Verdict: ✅ X" (emoji-prefixed value — QA agents commonly write this)
+    // The gap between "Verdict:" and the token tolerates any run of
+    // non-alphanumeric characters (emoji, ✅/❌/⚠️, asterisks, whitespace). A
+    // negated ASCII class (not an emoji literal class) keeps this ReDoS-safe and
+    // avoids the no-misleading-character-class lint, matching parseQaSummary's
+    // approach below. Without this, `Verdict: ✅ READY_FOR_MERGE` parsed as null
+    // and a genuine PASS was recorded as "completed without a parseable verdict"
+    // (live repro: `sequant run 687 --phases exec,qa`, 2026-06-01).
+    // Case insensitive, handles optional markdown formatting.
+    const verdictMatch = output.match(/(?:###?\s*)?(?:\*\*)?Verdict:?[^A-Za-z0-9_]*(READY_FOR_MERGE|AC_MET_BUT_NOT_A_PLUS|AC_NOT_MET|NEEDS_VERIFICATION)\*?\*?/i);
     if (!verdictMatch)
         return null;
     // Normalize to uppercase with underscores
@@ -377,6 +337,10 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         stdoutTail: agentResult.stdoutTail,
         exitCode: agentResult.exitCode,
     };
+    const resume = {
+        sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
+    };
     if (phase === "qa") {
         const verdict = agentResult.output
             ? parseQaVerdict(agentResult.output)
@@ -392,7 +356,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
                 success: false,
                 durationSeconds,
                 error: `QA verdict: ${verdict}`,
-                sessionId: agentResult.sessionId,
+                ...resume,
                 output: agentResult.output,
                 verdict,
                 summary,
@@ -406,7 +370,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
                 success: false,
                 durationSeconds,
                 error: "QA completed without a parseable verdict",
-                sessionId: agentResult.sessionId,
+                ...resume,
                 output: agentResult.output,
                 summary,
                 ...tails,
@@ -416,7 +380,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             phase,
             success: true,
             durationSeconds,
-            sessionId: agentResult.sessionId,
+            ...resume,
             output: agentResult.output,
             verdict,
             summary,
@@ -430,7 +394,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             success: false,
             durationSeconds,
             error: "exec produced no changes (no commits, no uncommitted work)",
-            sessionId: agentResult.sessionId,
+            ...resume,
             output: agentResult.output,
             ...tails,
         };
@@ -439,7 +403,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         phase,
         success: true,
         durationSeconds,
-        sessionId: agentResult.sessionId,
+        ...resume,
         output: agentResult.output,
         ...tails,
     };
@@ -453,8 +417,14 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
  * @internal Exported for testing only
  */
 export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
-    const prompts = agent && agent !== "claude-code" ? AIDER_PHASE_PROMPTS : PHASE_PROMPTS;
-    let basePrompt = prompts[phase].replace(/\{issue\}/g, String(issueNumber));
+    const definition = phaseRegistry.get(phase);
+    // Non-claude drivers consult driverOverrides[<driver>] first; fall back to
+    // the default promptTemplate when no override is registered for the driver.
+    const driverPrompt = agent && agent !== "claude-code"
+        ? definition.driverOverrides?.[agent]?.promptTemplate
+        : undefined;
+    const template = driverPrompt ?? definition.promptTemplate;
+    let basePrompt = template.replace(/\{issue\}/g, String(issueNumber));
     // Append phase-specific context (e.g., QA findings for loop phase)
     if (promptContext) {
         basePrompt += `\n\n---\n\n${promptContext}`;
@@ -471,14 +441,14 @@ export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
 /**
  * Execute a single phase for an issue using the configured AgentDriver.
  */
-async function executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner) {
+async function executePhase(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner) {
     const startTime = Date.now();
     const prompt = await getPhasePrompt(phase, issueNumber, config.agent, config.promptContext);
     if (config.dryRun) {
         // Dry run - show the prompt that would be sent, then return
         if (config.verbose) {
-            console.log(chalk.gray(`    Would execute: /${phase} ${issueNumber}`));
-            console.log(chalk.gray(`    Prompt: ${prompt}`));
+            bracketedConsoleLog(spinner, chalk.gray(`    Would execute: /${phase} ${issueNumber}`));
+            bracketedConsoleLog(spinner, chalk.gray(`    Prompt: ${prompt}`));
         }
         return {
             phase,
@@ -488,13 +458,13 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         };
     }
     if (config.verbose) {
-        console.log(chalk.gray(`    Prompt: ${prompt}`));
-        if (worktreePath && ISOLATED_PHASES.includes(phase)) {
-            console.log(chalk.gray(`    Worktree: ${worktreePath}`));
+        bracketedConsoleLog(spinner, chalk.gray(`    Prompt: ${prompt}`));
+        if (worktreePath && phaseRequiresWorktree(phase)) {
+            bracketedConsoleLog(spinner, chalk.gray(`    Worktree: ${worktreePath}`));
         }
     }
     // Determine working directory and environment
-    const shouldUseWorktree = worktreePath && ISOLATED_PHASES.includes(phase);
+    const shouldUseWorktree = worktreePath && phaseRequiresWorktree(phase);
     const cwd = shouldUseWorktree ? worktreePath : process.cwd();
     // Resolve file context for file-oriented drivers (e.g., Aider --file)
     let files;
@@ -546,6 +516,13 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
     // Skills can check these to skip redundant pre-flight checks
     env.SEQUANT_ORCHESTRATOR = "sequant-run";
     env.SEQUANT_PHASE = phase;
+    // #683: force full-weight QA. `sequant ready` sets config.fullQa so its QA
+    // pass runs the standalone branch-freshness / process-state pre-flight checks
+    // even though SEQUANT_ORCHESTRATOR is set unconditionally above. Scoped to the
+    // qa phase — the loop/exec phases don't have a git-trust skip to override.
+    if (config.fullQa && phase === "qa") {
+        env.SEQUANT_FULL_QA = "1";
+    }
     // Propagate issue type for skills to adapt behavior (e.g., lighter QA for docs)
     if (config.issueType) {
         env.SEQUANT_ISSUE_TYPE = config.issueType;
@@ -599,12 +576,19 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         }, ACTIVITY_THROTTLE_MS)
         : undefined;
     const reportActivity = throttle ? throttle.report : undefined;
-    // Safety: never resume a session when worktree isolation is active.
-    // Even if THIS phase doesn't use the worktree, a previous phase may have
-    // created the session there. Resuming from a different cwd crashes the SDK
-    // (exit code 1). ISOLATED_PHASES prevents this by design, but this guard
-    // catches edge cases (e.g. a new phase added without updating ISOLATED_PHASES).
-    const canResume = sessionId && !worktreePath;
+    // Resolve driver before the resume check — eligibility is now driver-owned
+    // (#674). Each driver's `canResume(handle, cwd)` enforces its own contract:
+    // Claude Code requires byte-equal cwd match (session storage is
+    // cwd-namespaced); Aider declines all resume (no session concept); Codex
+    // (when added in #497) folds in AGENTS.md parity. Replacing the prior
+    // `sessionId && !worktreePath` heuristic also unblocks same-worktree resume
+    // across phases.
+    const driver = getDriver(config.agent, {
+        aiderSettings: config.aiderSettings,
+    });
+    const eligibleHandle = resumeHandle && driver.canResume(resumeHandle, cwd)
+        ? resumeHandle
+        : undefined;
     // Build AgentExecutionConfig for the driver
     const agentConfig = {
         cwd,
@@ -613,7 +597,8 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         phaseTimeout: config.phaseTimeout,
         verbose: config.verbose,
         mcp: config.mcp,
-        sessionId: canResume ? sessionId : undefined,
+        resumeHandle: eligibleHandle,
+        sessionId: eligibleHandle?.token,
         files,
         onOutput: config.verbose || reportActivity
             ? (text) => {
@@ -622,6 +607,7 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                         spinner?.pause();
                         verboseStreamingActive = true;
                     }
+                    // eslint-disable-next-line no-restricted-syntax -- spinner is paused above; verbose subprocess streaming bypasses log-update intentionally.
                     process.stdout.write(chalk.gray(text));
                 }
                 reportActivity?.(text);
@@ -633,14 +619,11 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                     spinner?.pause();
                     verboseStreamingActive = true;
                 }
+                // eslint-disable-next-line no-restricted-syntax -- spinner is paused above; verbose subprocess streaming bypasses log-update intentionally.
                 process.stderr.write(chalk.red(data));
             }
             : undefined,
     };
-    // Resolve driver from config or default
-    const driver = getDriver(config.agent, {
-        aiderSettings: config.aiderSettings,
-    });
     const agentResult = await driver.executePhase(prompt, agentConfig);
     // Cancel any pending trailing activity fire — phase is done; the
     // orchestrator's stale-phase guard would no-op a late call anyway, but
@@ -665,6 +648,7 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         durationSeconds,
         error: agentResult.error,
         sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
         stderrTail: agentResult.stderrTail,
         stdoutTail: agentResult.stdoutTail,
         exitCode: agentResult.exitCode,
@@ -684,24 +668,28 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
 /**
  * @internal Exported for testing only
  */
-export async function executePhaseWithRetry(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner, 
+export async function executePhaseWithRetry(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner, 
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn = executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
 delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // Skip retry logic if explicitly disabled
     if (config.retry === false) {
-        return executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
-    }
-    // Skip cold-start retries for `loop` phase (#488).
-    // Loop is always a re-run after a failed QA — never a first boot.
-    // Failures at 47-51s are genuine skill failures, not cold-start issues.
-    // Without this guard, 2 cold-start retries + 1 MCP fallback = 3 wasted spawns per loop.
-    const skipColdStartRetry = phase === "loop";
+        return executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
+    }
+    // Skip cold-start retries for phases registered with `retryStrategy.maxRetries: 0`.
+    // `loop` is the canonical user (#488) — it's always a re-run after a failed QA,
+    // never a first boot. Failures at 47-51s are genuine skill failures, not cold-start
+    // issues. Without this guard, 2 cold-start retries + 1 MCP fallback = 3 wasted
+    // spawns per loop. Sourcing the decision from the registry makes the rule
+    // data-driven — any future phase registered with `maxRetries: 0` inherits the
+    // same behavior without a code change here.
+    const skipColdStartRetry = phaseRegistry.has(phase) &&
+        phaseRegistry.get(phase).retryStrategy?.maxRetries === 0;
     let lastResult;
     if (skipColdStartRetry) {
         // Single attempt — no cold-start retry loop
-        lastResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+        lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
         if (lastResult.success) {
             return lastResult;
         }
@@ -709,7 +697,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     else {
         // Phase 1: Cold-start retry attempts (with MCP enabled if configured)
         for (let attempt = 0; attempt <= COLD_START_MAX_RETRIES; attempt++) {
-            lastResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+            lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
             const duration = lastResult.durationSeconds ?? 0;
             // Success → return immediately
             if (lastResult.success) {
@@ -725,7 +713,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
                         const label = typedError instanceof ApiError
                             ? `API error (status ${typedError.metadata.statusCode ?? "unknown"})`
                             : typedError.name;
-                        console.log(chalk.yellow(`\n    ⟳ Retryable error: ${label}, retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                        bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Retryable error: ${label}, retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
                     }
                     continue;
                 }
@@ -737,7 +725,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             // Cold-start failure detected — retry
             if (attempt < COLD_START_MAX_RETRIES) {
                 if (config.verbose) {
-                    console.log(chalk.yellow(`\n    ⟳ Cold-start failure detected (${duration.toFixed(1)}s), retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                    bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Cold-start failure detected (${duration.toFixed(1)}s), retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
                 }
             }
         }
@@ -748,15 +736,15 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // This handles npx-based MCP servers that fail on first run due to cold-cache issues.
     // Skip for `loop` phase — MCP is never the cause of loop failures (#488).
     if (config.mcp && !lastResult.success && !skipColdStartRetry) {
-        console.log(chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
+        bracketedConsoleLog(spinner, chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
         // Create config copy with MCP disabled
         const configWithoutMcp = {
             ...config,
             mcp: false,
         };
-        const retryResult = await executePhaseFn(issueNumber, phase, configWithoutMcp, sessionId, worktreePath, shutdownManager, spinner);
+        const retryResult = await executePhaseFn(issueNumber, phase, configWithoutMcp, resumeHandle, worktreePath, shutdownManager, spinner);
         if (retryResult.success) {
-            console.log(chalk.green(`    ✓ Phase succeeded without MCP (MCP cold-start issue detected)`));
+            bracketedConsoleLog(spinner, chalk.green(`    ✓ Phase succeeded without MCP (MCP cold-start issue detected)`));
             return retryResult;
         }
         // Update lastResult for Phase 3 (spec retry)
@@ -773,11 +761,11 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // than other phases (~8.6%), so one extra retry with backoff recovers most cases.
     if (phase === "spec" && !lastResult.success) {
         for (let i = 0; i < SPEC_EXTRA_RETRIES; i++) {
-            console.log(chalk.yellow(`\n    ⟳ Spec phase failed, retrying with ${SPEC_RETRY_BACKOFF_MS}ms backoff... (spec retry ${i + 1}/${SPEC_EXTRA_RETRIES})`));
+            bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Spec phase failed, retrying with ${SPEC_RETRY_BACKOFF_MS}ms backoff... (spec retry ${i + 1}/${SPEC_EXTRA_RETRIES})`));
             await delayFn(SPEC_RETRY_BACKOFF_MS);
-            const specRetryResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+            const specRetryResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
             if (specRetryResult.success) {
-                console.log(chalk.green(`    ✓ Spec phase succeeded on retry`));
+                bracketedConsoleLog(spinner, chalk.green(`    ✓ Spec phase succeeded on retry`));
                 return specRetryResult;
             }
             lastResult = specRetryResult;

package/dist/src/lib/workflow/phase-mapper.d.ts

@@ -17,27 +17,35 @@ interface PhaseMapperOptions {
     securityReview?: boolean;
 }
 /**
- * UI-related labels that trigger automatic test phase
- */
-export declare const UI_LABELS: string[];
-/**
- * Bug-related labels (used by downstream metadata consumers)
+ * Bug-related labels (used by downstream metadata consumers).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. The registry-driven
+ * `detectPhasesFromLabels` below does not consult this list. It stays
+ * here because `batch-executor.ts` and other modules read it for
+ * `issueType` propagation and similar non-phase concerns.
  */
 export declare const BUG_LABELS: string[];
 /**
- * Documentation labels (used for issueType propagation and downstream metadata)
+ * Documentation labels (used for issueType propagation and downstream metadata).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. See BUG_LABELS comment.
  */
 export declare const DOCS_LABELS: string[];
 /**
- * Complex labels that enable quality loop
+ * Complex labels that enable quality loop.
+ *
+ * Quality-loop trigger — NOT a phase-trigger rule (does not add the loop
+ * *phase*; only flips the `qualityLoop` flag on the run config). Kept
+ * out of the phase registry by design.
  */
 export declare const COMPLEX_LABELS: string[];
 /**
- * Security-related labels that trigger security-review phase
- */
-export declare const SECURITY_LABELS: string[];
-/**
- * Detect phases based on issue labels (like /assess logic)
+ * Detect phases based on issue labels (like /assess logic).
+ *
+ * Label → phase mapping now lives in `PhaseDefinition.detect.labels`. Only
+ * the *insertion position* of detected phases remains baked in here, because
+ * pipeline ordering depends on the phase's role (security-review goes after
+ * spec; test goes before qa).
  */
 export declare function detectPhasesFromLabels(labels: string[]): {
     phases: Phase[];
@@ -56,7 +64,12 @@ export declare function parseRecommendedWorkflow(output: string): {
     qualityLoop: boolean;
 } | null;
 /**
- * Check if an issue has UI-related labels
+ * Check if an issue has UI-related labels.
+ *
+ * Sources the label list from the `test` phase's `detect.labels` entry in
+ * the registry — same data as `detectPhasesFromLabels` consults, just
+ * exposed as a boolean for callers that only need the yes/no answer
+ * (e.g. test phase insertion in `determinePhasesForIssue`).
  */
 export declare function hasUILabels(labels: string[]): boolean;
 /**

package/dist/src/lib/workflow/phase-mapper.js

@@ -7,43 +7,62 @@
  *
  * @module phase-mapper
  */
+import { phaseRegistry } from "./phase-registry.js";
 /**
- * UI-related labels that trigger automatic test phase
- */
-export const UI_LABELS = ["ui", "frontend", "admin", "web", "browser"];
-/**
- * Bug-related labels (used by downstream metadata consumers)
+ * Bug-related labels (used by downstream metadata consumers).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. The registry-driven
+ * `detectPhasesFromLabels` below does not consult this list. It stays
+ * here because `batch-executor.ts` and other modules read it for
+ * `issueType` propagation and similar non-phase concerns.
  */
 export const BUG_LABELS = ["bug", "fix", "hotfix", "patch"];
 /**
- * Documentation labels (used for issueType propagation and downstream metadata)
+ * Documentation labels (used for issueType propagation and downstream metadata).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. See BUG_LABELS comment.
  */
 export const DOCS_LABELS = ["docs", "documentation", "readme"];
 /**
- * Complex labels that enable quality loop
+ * Complex labels that enable quality loop.
+ *
+ * Quality-loop trigger — NOT a phase-trigger rule (does not add the loop
+ * *phase*; only flips the `qualityLoop` flag on the run config). Kept
+ * out of the phase registry by design.
  */
 export const COMPLEX_LABELS = ["complex", "refactor", "breaking", "major"];
 /**
- * Security-related labels that trigger security-review phase
+ * Look up label-based detect rules from the registry, returning the set
+ * of phases whose `detect.labels` intersect the issue's labels. Comparison
+ * is case-insensitive (labels lowercased at the call site).
  */
-export const SECURITY_LABELS = [
-    "security",
-    "auth",
-    "authentication",
-    "permissions",
-    "admin",
-];
+function detectPhasesFromRegistry(lowerLabels) {
+    const matched = new Set();
+    for (const def of phaseRegistry.list()) {
+        const triggers = def.detect?.labels;
+        if (!triggers || triggers.length === 0)
+            continue;
+        const hit = triggers.some((t) => lowerLabels.includes(t.toLowerCase()));
+        if (hit)
+            matched.add(def.name);
+    }
+    return matched;
+}
 /**
- * Detect phases based on issue labels (like /assess logic)
+ * Detect phases based on issue labels (like /assess logic).
+ *
+ * Label → phase mapping now lives in `PhaseDefinition.detect.labels`. Only
+ * the *insertion position* of detected phases remains baked in here, because
+ * pipeline ordering depends on the phase's role (security-review goes after
+ * spec; test goes before qa).
  */
 export function detectPhasesFromLabels(labels) {
     const lowerLabels = labels.map((l) => l.toLowerCase());
-    // Check for UI labels → add test phase
-    const isUI = lowerLabels.some((label) => UI_LABELS.some((uiLabel) => label === uiLabel));
-    // Check for complex labels → enable quality loop
+    // Quality loop is a registry-independent label trigger (see COMPLEX_LABELS).
     const isComplex = lowerLabels.some((label) => COMPLEX_LABELS.some((complexLabel) => label === complexLabel));
-    // Check for security labels → add security-review phase
-    const isSecurity = lowerLabels.some((label) => SECURITY_LABELS.some((secLabel) => label === secLabel));
+    const matched = detectPhasesFromRegistry(lowerLabels);
+    const isUI = matched.has("test");
+    const isSecurity = matched.has("security-review");
     // Build phase list — spec is always included by default (#533).
     // Bug/docs labels no longer short-circuit spec; downstream consumers
     // (e.g. `issueType: "docs"` propagation) still use DOCS_LABELS for
@@ -78,18 +97,10 @@ export function parseRecommendedWorkflow(output) {
         .split(/\s*→\s*|\s*->\s*|\s*,\s*/)
         .map((p) => p.trim().toLowerCase())
         .filter((p) => p.length > 0);
-    // Validate and convert to Phase type
+    // Validate against the registry — accepts any registered phase.
     const validPhases = [];
     for (const name of phaseNames) {
-        if ([
-            "spec",
-            "security-review",
-            "testgen",
-            "exec",
-            "test",
-            "qa",
-            "loop",
-        ].includes(name)) {
+        if (phaseRegistry.has(name)) {
             validPhases.push(name);
         }
     }
@@ -104,10 +115,21 @@ export function parseRecommendedWorkflow(output) {
     return { phases: validPhases, qualityLoop };
 }
 /**
- * Check if an issue has UI-related labels
+ * Check if an issue has UI-related labels.
+ *
+ * Sources the label list from the `test` phase's `detect.labels` entry in
+ * the registry — same data as `detectPhasesFromLabels` consults, just
+ * exposed as a boolean for callers that only need the yes/no answer
+ * (e.g. test phase insertion in `determinePhasesForIssue`).
  */
 export function hasUILabels(labels) {
-    return labels.some((label) => UI_LABELS.some((uiLabel) => label.toLowerCase() === uiLabel));
+    const testTriggers = phaseRegistry.has("test")
+        ? (phaseRegistry.get("test").detect?.labels ?? [])
+        : [];
+    if (testTriggers.length === 0)
+        return false;
+    const lowered = new Set(testTriggers.map((t) => t.toLowerCase()));
+    return labels.some((label) => lowered.has(label.toLowerCase()));
 }
 /**
  * Determine phases to run based on options and issue labels