sequant 1.17.0 → 1.18.0

package/dist/marketplace/external_plugins/sequant/skills/verify/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: verify
+description: Execution verification for CLI/script features — runs commands and captures output for human review. Use after /exec for script changes.
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Bash(*)
+  - Read
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+---
+
+# Execution Verification
+
+You are the "Execution Verification Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/verify`, your job is to:
+
+1. Run the specified command for a CLI/script feature.
+2. Capture and display the command output (stdout/stderr).
+3. Prompt for human confirmation that output matches expected behavior.
+4. Post verification evidence to the GitHub issue.
+
+This is the CLI equivalent of `/test` (which handles UI features via browser testing).
+
+## When to Use
+
+Use `/verify` for:
+- New scripts in `scripts/`
+- CLI tool changes
+- Automation features
+- Anything with terminal output as primary interface
+
+## Invocation
+
+```bash
+# With explicit command
+/verify 559 --command "npx tsx scripts/migrate.ts --dry-run"
+
+# With issue only (will prompt for command)
+/verify 559
+```
+
+## Behavior
+
+### 1. Parse Arguments
+
+Extract from the invocation:
+- **Issue number:** The GitHub issue being verified
+- **Command:** The command to execute (from `--command` flag or prompted)
+
+If no command provided:
+```
+Ask: "What command should I run to verify this feature?"
+```
+
+### 2. Verify Issue Context
+
+```bash
+# Get issue details
+gh issue view <issue-number> --json title,body,labels
+```
+
+Confirm this is a CLI/script feature by checking:
+- Issue title/body mentions scripts, CLI, automation
+- Files changed include `scripts/` directory
+- Not a UI-only feature
+
+### 3. Execute Command
+
+Run the specified command with a timeout:
+
+```bash
+# Run with 2-minute timeout, capture both stdout and stderr
+timeout 120 <command> 2>&1
+```
+
+**Timeout handling:**
+- Default: 2 minutes (120 seconds)
+- If command exceeds timeout, capture partial output and note timeout
+
+**Output capture:**
+- Capture both stdout and stderr
+- Truncate at 500 lines to prevent oversized GitHub comments
+- Preserve formatting (colors stripped for readability)
+
+### 4. Display Output
+
+Present the captured output to the user:
+
+```markdown
+## Execution Output
+
+**Command:** `<command>`
+**Exit code:** <0 or error code>
+**Duration:** <X seconds>
+
+<details>
+<summary>Output (X lines)</summary>
+
+```
+[captured output here]
+```
+
+</details>
+```
+
+### 5. Prompt for Confirmation
+
+Use AskUserQuestion to get human confirmation:
+
+```
+Question: Does this output match expected behavior for the feature?
+
+Options:
+- Yes, looks correct
+- Partially - some issues but acceptable
+- No, something is wrong
+```
+
+### 6. Handle Confirmation Response
+
+**If "Yes" or "Partially":**
+- Prepare verification evidence comment for GitHub
+- Include: command, exit code, output summary, human confirmation
+
+**If "No":**
+- Ask for details about what's wrong
+- Do NOT post verification (feature needs fixes)
+- Suggest running `/exec` to address issues
+
+### 7. Post Verification to GitHub Issue
+
+Post a comment with verification evidence:
+
+```markdown
+## Execution Verification
+
+**Command:** `<command>`
+**Result:** Verified by human review
+
+<details>
+<summary>Execution Output (click to expand)</summary>
+
+**Exit code:** <code>
+**Duration:** <duration>
+
+```
+[truncated output - first 100 lines]
+```
+
+[Output truncated at 100 lines - X total lines captured]
+
+</details>
+
+**Human Confirmation:**
+> <confirmation response and any notes>
+
+---
+*Verified by `/verify` command*
+```
+
+### 8. Exit Code Handling
+
+Handle non-zero exit codes gracefully:
+
+| Exit Code | Interpretation |
+|-----------|----------------|
+| 0 | Success |
+| 1-125 | Command failed (show error output) |
+| 124 | Timeout (command exceeded 2 minutes) |
+| 126 | Permission denied |
+| 127 | Command not found |
+
+For non-zero exits:
+- Still display output
+- Still ask for confirmation (failure might be expected for testing error paths)
+- Note the failure in the verification comment
+
+## Output Truncation
+
+To prevent oversized GitHub comments (64KB limit):
+
+1. Capture full output to temp file
+2. Count lines
+3. If > 500 lines:
+   - Show first 100 lines in comment
+   - Note: "[Output truncated at 100 lines - X total lines captured]"
+4. Preserve full output locally for reference
+
+## Examples
+
+### Example 1: Successful Verification
+
+```bash
+/verify 558 --command "npx tsx scripts/migrate.ts --dry-run"
+```
+
+Output:
+```
+Starting migration (dry run)...
+Checking tables...
+Migration plan: 3 tables, 5 columns
+...
+Completed successfully
+```
+
+Human confirms: "Yes, looks correct"
+
+-> Posts verification evidence to issue #558
+
+### Example 2: Command Failure (Expected)
+
+```bash
+/verify 559 --command "npx tsx scripts/dev/test-error-handling.ts --trigger-error"
+```
+
+Output:
+```
+Triggering intentional error...
+Error: Test error triggered as expected
+Exit code: 1
+```
+
+Human confirms: "Yes, this error was expected - testing error handling"
+
+-> Posts verification evidence noting expected failure
+
+### Example 3: No Command Provided
+
+```bash
+/verify 560
+```
+
+Agent prompts: "What command should I run to verify this feature?"
+
+User provides: "npx tsx scripts/audit/check-coverage.ts nashville"
+
+-> Proceeds with verification
+
+## Integration with /qa
+
+The `/qa` skill will:
+1. Detect when `scripts/` files are modified
+2. Prompt to run `/verify` before `READY_FOR_MERGE`
+3. Check for "Execution Verification" section in issue comments
+
+This ensures CLI/script features are actually tested, not just code-reviewed.
+
+## Error Recovery
+
+If verification fails due to infrastructure issues:
+
+1. **Network timeout:** Retry once, then note as infrastructure issue
+2. **Missing dependencies:** Run `npm install` and retry
+3. **Environment issues:** Check for `.env.local` and required vars
+4. **File not found:** Verify worktree is correct, check file paths
+
+Report infrastructure issues separately from feature issues.
+
+---
+
+## Output Verification
+
+**Before responding, verify your output includes ALL of these:**
+
+- [ ] **Command Executed** - The exact command that was run
+- [ ] **Exit Code** - Success (0) or error code
+- [ ] **Duration** - How long the command took
+- [ ] **Output Sample** - Captured stdout/stderr (truncated if needed)
+- [ ] **Human Confirmation** - User's verification response recorded
+- [ ] **GitHub Comment** - Verification evidence posted to issue
+
+**DO NOT respond until all items are verified.**

package/dist/src/commands/run.d.ts

@@ -1,287 +1,20 @@
 /**
  * sequant run - Execute workflow for GitHub issues
  *
- * Runs the Sequant workflow (/spec → /exec → /qa) for one or more issues
- * using the Claude Agent SDK for proper skill invocation.
- */
-import { Phase, ExecutionConfig, PhaseResult, QaVerdict } from "../lib/workflow/types.js";
-import { ShutdownManager } from "../lib/shutdown.js";
-import { PhaseSpinner } from "../lib/phase-spinner.js";
-/**
- * Parse QA verdict from phase output
- *
- * Looks for verdict patterns in the QA output:
- * - "### Verdict: READY_FOR_MERGE"
- * - "**Verdict:** AC_NOT_MET"
- * - "Verdict: AC_MET_BUT_NOT_A_PLUS"
- *
- * @param output - The captured output from QA phase
- * @returns The parsed verdict or null if not found
- */
-export declare function parseQaVerdict(output: string): QaVerdict | null;
-/**
- * Result of worktree freshness check
- */
-interface WorktreeFreshnessResult {
-    /** True if worktree is stale (significantly behind main) */
-    isStale: boolean;
-    /** Number of commits behind origin/main */
-    commitsBehind: number;
-    /** True if worktree has uncommitted changes */
-    hasUncommittedChanges: boolean;
-    /** True if worktree has unpushed commits */
-    hasUnpushedCommits: boolean;
-}
-/**
- * Check if a worktree is stale (behind origin/main) and should be recreated
- *
- * @param worktreePath - Path to the worktree
- * @param verbose - Enable verbose output
- * @returns Freshness check result
- */
-export declare function checkWorktreeFreshness(worktreePath: string, verbose: boolean): WorktreeFreshnessResult;
-/**
- * Remove and recreate a stale worktree
- *
- * @param existingPath - Path to existing worktree
- * @param branch - Branch name
- * @param verbose - Enable verbose output
- * @returns true if worktree was removed
- */
-export declare function removeStaleWorktree(existingPath: string, branch: string, verbose: boolean): boolean;
-/**
- * List all active worktrees with their branches
- */
-export declare function listWorktrees(): Array<{
-    path: string;
-    branch: string;
-    issue: number | null;
-}>;
-/**
- * Get changed files in a worktree compared to main
- */
-export declare function getWorktreeChangedFiles(worktreePath: string): string[];
-/**
- * Get diff stats for a worktree (files changed, lines added)
- * Returns aggregate metrics only - no file paths to preserve privacy
- */
-export declare function getWorktreeDiffStats(worktreePath: string): {
-    filesChanged: number;
-    linesAdded: number;
-};
-/**
- * Filter phases based on resume status.
- *
- * When `resume` is true, calls `getResumablePhasesForIssue` to determine
- * which phases have already completed (via GitHub issue comment markers)
- * and removes them from the execution list.
- *
- * @param issueNumber - GitHub issue number
- * @param phases - The phases to potentially filter
- * @param resume - Whether the --resume flag is set
- * @returns Object with filtered phases and any skipped phases
- */
-export declare function filterResumedPhases(issueNumber: number, phases: Phase[], resume: boolean): {
-    phases: Phase[];
-    skipped: Phase[];
-};
-/**
- * Create a checkpoint commit in the worktree after QA passes
- * This allows recovery in case later issues in the chain fail
- * @internal Exported for testing
- */
-export declare function createCheckpointCommit(worktreePath: string, issueNumber: number, verbose: boolean): boolean;
-/**
- * Check if any lockfile changed during a rebase and re-run install if needed.
- * This prevents dependency drift when the lockfile was updated on main.
- * @param worktreePath Path to the worktree
- * @param packageManager Package manager to use for install
- * @param verbose Whether to show verbose output
- * @param preRebaseRef Git ref pointing to pre-rebase HEAD (defaults to ORIG_HEAD,
- *        which git sets automatically after rebase). Using ORIG_HEAD captures all
- *        lockfile changes across multi-commit rebases, unlike HEAD~1 which only
- *        checks the last commit.
- * @returns true if reinstall was performed, false otherwise
- * @internal Exported for testing
- */
-export declare function reinstallIfLockfileChanged(worktreePath: string, packageManager: string | undefined, verbose: boolean, preRebaseRef?: string): boolean;
-/**
- * Result of a pre-PR rebase operation
- */
-export interface RebaseResult {
-    /** Whether the rebase was performed */
-    performed: boolean;
-    /** Whether the rebase succeeded */
-    success: boolean;
-    /** Whether dependencies were reinstalled */
-    reinstalled: boolean;
-    /** Error message if rebase failed */
-    error?: string;
-}
-/**
- * Rebase the worktree branch onto origin/main before PR creation.
- * This ensures the branch is up-to-date and prevents lockfile drift.
- *
- * @param worktreePath Path to the worktree
- * @param issueNumber Issue number (for logging)
- * @param packageManager Package manager to use if reinstall needed
- * @param verbose Whether to show verbose output
- * @returns RebaseResult indicating success/failure and whether reinstall was performed
- * @internal Exported for testing
- */
-export declare function rebaseBeforePR(worktreePath: string, issueNumber: number, packageManager: string | undefined, verbose: boolean): RebaseResult;
-/**
- * Result of PR creation
- */
-export interface PRCreationResult {
-    /** Whether PR creation was attempted */
-    attempted: boolean;
-    /** Whether PR was created successfully (or already existed) */
-    success: boolean;
-    /** PR number */
-    prNumber?: number;
-    /** PR URL */
-    prUrl?: string;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Push branch and create a PR after successful QA.
- *
- * Handles both fresh PR creation and detection of existing PRs.
- * Failures are warnings — they don't fail the run.
- *
- * @param worktreePath Path to the worktree
- * @param issueNumber Issue number
- * @param issueTitle Issue title (for PR title)
- * @param branch Branch name
- * @param verbose Whether to show verbose output
- * @returns PRCreationResult with PR info or error
- * @internal Exported for testing
- */
-export declare function createPR(worktreePath: string, issueNumber: number, issueTitle: string, branch: string, verbose: boolean, labels?: string[]): PRCreationResult;
-/**
- * Detect phases based on issue labels (like /solve logic)
- */
-export declare function detectPhasesFromLabels(labels: string[]): {
-    phases: Phase[];
-    qualityLoop: boolean;
-};
-/**
- * Parse recommended workflow from /spec output
- *
- * Looks for:
- * ## Recommended Workflow
- * **Phases:** exec → qa
- * **Quality Loop:** enabled|disabled
- */
-export declare function parseRecommendedWorkflow(output: string): {
-    phases: Phase[];
-    qualityLoop: boolean;
-} | null;
-interface RunOptions {
-    phases?: string;
-    sequential?: boolean;
-    dryRun?: boolean;
-    verbose?: boolean;
-    timeout?: number;
-    logJson?: boolean;
-    noLog?: boolean;
-    logPath?: string;
-    qualityLoop?: boolean;
-    maxIterations?: number;
-    batch?: string[];
-    smartTests?: boolean;
-    noSmartTests?: boolean;
-    testgen?: boolean;
-    autoDetectPhases?: boolean;
-    /** Enable automatic worktree creation for issue isolation */
-    worktreeIsolation?: boolean;
-    /** Reuse existing worktrees instead of creating new ones */
-    reuseWorktrees?: boolean;
-    /** Suppress version warnings and non-essential output */
-    quiet?: boolean;
-    /** Chain issues: each branches from previous (requires --sequential) */
-    chain?: boolean;
-    /**
-     * Wait for QA pass before starting next issue in chain mode.
-     * When enabled, the chain pauses if QA fails, preventing downstream issues
-     * from building on potentially broken code.
-     */
-    qaGate?: boolean;
-    /**
-     * Base branch for worktree creation.
-     * Resolution priority: this CLI flag → settings.run.defaultBase → 'main'
-     */
-    base?: string;
-    /**
-     * Disable MCP servers in headless mode.
-     * When true, MCPs are not passed to the SDK (faster/cheaper runs).
-     * Resolution priority: this CLI flag → settings.run.mcp → default (true)
-     */
-    noMcp?: boolean;
-    /**
-     * Resume from last completed phase.
-     * Reads phase markers from GitHub issue comments and skips completed phases.
-     */
-    resume?: boolean;
-    /**
-     * Disable automatic retry with MCP fallback.
-     * When true, no retry attempts are made on phase failure.
-     * Useful for debugging to see the actual failure without retry masking it.
-     */
-    noRetry?: boolean;
-    /**
-     * Skip pre-PR rebase onto origin/main.
-     * When true, branches are not rebased before creating the PR.
-     * Use when you want to preserve branch state or handle rebasing manually.
-     */
-    noRebase?: boolean;
-    /**
-     * Skip PR creation after successful QA.
-     * When true, branches are pushed but no PR is created.
-     * Useful for manual workflows where PRs are created separately.
-     */
-    noPr?: boolean;
-    /**
-     * Force re-execution of issues even if they have completed status.
-     * Bypasses the pre-flight state guard that skips ready_for_merge/merged issues.
-     */
-    force?: boolean;
-    /**
-     * Analyze run results and suggest workflow improvements.
-     * Displays observations about timing patterns, phase mismatches, and
-     * actionable suggestions after the summary output.
-     */
-    reflect?: boolean;
-}
-/**
- * Execute a single phase for an issue using Claude Agent SDK
- */
-declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhaseSpinner): Promise<PhaseResult & {
-    sessionId?: string;
-}>;
-/**
- * Execute a phase with automatic retry for cold-start failures and MCP fallback.
- *
- * Retry strategy:
- * 1. If phase fails within COLD_START_THRESHOLD_SECONDS, retry up to COLD_START_MAX_RETRIES times
- * 2. If still failing and MCP is enabled, retry once with MCP disabled (npx-based MCP servers
- *    can fail on first run due to cold-cache issues)
- *
- * The MCP fallback is safe because MCP servers are optional enhancements, not required
- * for core functionality.
- */
-/**
- * @internal Exported for testing only
- */
-export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhaseSpinner, 
-/** @internal Injected for testing — defaults to module-level executePhase */
-executePhaseFn?: typeof executePhase): Promise<PhaseResult & {
-    sessionId?: string;
-}>;
+ * Orchestrator module that composes focused workflow modules:
+ * - worktree-manager: Worktree lifecycle (ensure, list, cleanup, changed files)
+ * - phase-executor: Phase execution with retry and failure handling
+ * - phase-mapper: Label-to-phase detection and workflow parsing
+ * - batch-executor: Batch execution, dependency sorting, issue logging
+ */
+import type { RunOptions } from "../lib/workflow/batch-executor.js";
+export { parseQaVerdict, formatDuration, executePhaseWithRetry, } from "../lib/workflow/phase-executor.js";
+export { detectDefaultBranch, checkWorktreeFreshness, removeStaleWorktree, listWorktrees, getWorktreeChangedFiles, getWorktreeDiffStats, readCacheMetrics, filterResumedPhases, ensureWorktree, createCheckpointCommit, reinstallIfLockfileChanged, rebaseBeforePR, createPR, } from "../lib/workflow/worktree-manager.js";
+export type { WorktreeInfo, RebaseResult, PRCreationResult, } from "../lib/workflow/worktree-manager.js";
+export { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, } from "../lib/workflow/phase-mapper.js";
+export { getIssueInfo, sortByDependencies, parseBatches, getEnvConfig, executeBatch, runIssueWithLogging, } from "../lib/workflow/batch-executor.js";
+export type { RunOptions } from "../lib/workflow/batch-executor.js";
 /**
  * Main run command
  */
 export declare function runCommand(issues: string[], options: RunOptions): Promise<void>;
-export {};