sequant 2.0.0 → 2.1.0

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

@@ -42,10 +42,127 @@ The `/test` phase is invoked by `/fullsolve` based on issue labels:
 2. **Execution Phase:** Run tests systematically with browser automation
 3. **Reporting Phase:** Generate test results and GitHub comment
 
+## Orchestration Context
+
+When running as part of an orchestrated workflow (e.g., `sequant run` or `/fullsolve`), this skill receives environment variables that indicate the orchestration context:
+
+| Environment Variable | Description | Example Value |
+|---------------------|-------------|---------------|
+| `SEQUANT_ORCHESTRATOR` | The orchestrator invoking this skill | `sequant-run` |
+| `SEQUANT_PHASE` | Current phase in the workflow | `test` |
+| `SEQUANT_ISSUE` | Issue number being processed | `123` |
+| `SEQUANT_WORKTREE` | Path to the feature worktree | `/path/to/worktrees/feature/...` |
+
+**Behavior when orchestrated (SEQUANT_ORCHESTRATOR is set):**
+
+1. **Skip issue fetch** - Use `SEQUANT_ISSUE` directly, orchestrator has context
+2. **Use provided worktree** - Work in `SEQUANT_WORKTREE` path
+3. **Reduce GitHub comment frequency** - Defer progress updates to orchestrator
+4. **Trust dev server status** - Orchestrator may have started it already
+
+**Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
+
+- Fetch fresh issue context from GitHub
+- Locate or prompt for worktree
+- Post progress updates to GitHub
+- Start dev server if needed
+
+## Pre-flight: Stale Branch Detection
+
+**Skip this section if `SEQUANT_ORCHESTRATOR` is set** - the orchestrator handles branch freshness checks.
+
+**Purpose:** Detect when the feature branch is significantly behind main before running browser tests. Testing stale code is wasteful because:
+- Test results may not apply to the merged state
+- Features may have conflicts that need resolution first
+- Time spent on testing is lost if rebase is required
+
+**Detection:**
+
+```bash
+# Ensure we have latest remote state
+git fetch origin 2>/dev/null || true
+
+# Count commits behind main
+behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo "0")
+echo "Feature branch is $behind commits behind main"
+```
+
+**Threshold Configuration:**
+
+The stale branch threshold is configurable in `.sequant/settings.json`:
+
+```json
+{
+  "run": {
+    "staleBranchThreshold": 5
+  }
+}
+```
+
+Default: 5 commits
+
+**Behavior:**
+
+| Commits Behind | Action |
+|----------------|--------|
+| 0 | ✅ Proceed normally |
+| 1 to threshold | ⚠️ **Warning:** "Feature branch is N commits behind main. Consider rebasing before testing." |
+| > threshold | ❌ **Block:** "STALE_BRANCH: Feature branch is N commits behind main (threshold: T). Rebase required before testing." |
+
+**Implementation:**
+
+```bash
+# Read threshold from settings (default: 5)
+threshold=$(jq -r '.run.staleBranchThreshold // 5' .sequant/settings.json 2>/dev/null || echo "5")
+
+behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo "0")
+
+if [[ $behind -gt $threshold ]]; then
+  echo "❌ STALE_BRANCH: Feature branch is $behind commits behind main (threshold: $threshold)"
+  echo "   Rebase required before testing:"
+  echo "   git fetch origin && git rebase origin/main"
+  # Exit with error - testing should not proceed
+  exit 1
+elif [[ $behind -gt 0 ]]; then
+  echo "⚠️ Warning: Feature branch is $behind commits behind main."
+  echo "   Consider rebasing before testing: git fetch origin && git rebase origin/main"
+  # Continue with warning
+fi
+```
+
+**Output Format:**
+
+```markdown
+### Stale Branch Check
+
+| Check | Value |
+|-------|-------|
+| Commits behind main | N |
+| Threshold | T |
+| Status | ✅ OK / ⚠️ Warning / ❌ Blocked |
+
+[Warning/blocking message if applicable]
+```
+
+**Verdict Impact:**
+
+| Status | Verdict Impact |
+|--------|----------------|
+| OK (0 behind) | No impact |
+| Warning (1 to threshold) | Note in test output, recommend rebase |
+| Blocked (> threshold) | **Cannot proceed** - rebase first |
+
 ## Phase 1: Setup
 
 ### 1.1 Fetch Issue Context
 
+**If orchestrated (SEQUANT_ORCHESTRATOR is set):**
+- Use `SEQUANT_ISSUE` for the issue number
+- Skip fetching issue context (orchestrator has already done this)
+- Parse any context passed in the orchestrator's prompt
+
+**If standalone:**
+
 ```bash
 gh issue view <issue-number> --json title,body,labels
 gh issue view <issue-number> --comments
@@ -132,7 +249,99 @@ Wait for server ready before proceeding.
 
 **Note:** If `{{DEV_URL}}` or `{{PM_RUN}}` are not replaced with actual values, the defaults are:
 - DEV_URL: `http://localhost:3000` (Next.js), `http://localhost:4321` (Astro), `http://localhost:5173` (Vite-based)
-- PM_RUN: `npm run` (or `bun run`, `yarn`, `pnpm run` based on lockfile)
+- PM_RUN: `npm run` (or `bun run`, `yarn`, `pnpm run`, `poetry run`, `uv run`, `python -m` based on lockfile)
+
+### 1.5 Test Coverage Analysis (REQUIRED)
+
+**Purpose:** Warn when new/modified source files lack corresponding test files.
+
+**Before executing tests**, analyze coverage for changed files:
+
+1. **Get changed source files:**
+   ```bash
+   # Get changed source files (excluding tests themselves)
+   changed=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$' | grep -v -E '\.test\.|\.spec\.|__tests__' || true)
+   echo "Changed source files:"
+   echo "$changed"
+   ```
+
+2. **Check for corresponding test files:**
+   ```bash
+   # For each changed file, check if a test file exists
+   for file in $changed; do
+     base=$(basename "$file" | sed -E 's/\.(ts|tsx|js|jsx)$//')
+     dir=$(dirname "$file")
+
+     # Look for test files in common locations
+     test_found=false
+
+     # Check co-located test file
+     if ls "$dir/$base.test."* 2>/dev/null | grep -q .; then
+       test_found=true
+     fi
+
+     # Check __tests__ directory
+     if ls "$dir/__tests__/$base.test."* 2>/dev/null | grep -q .; then
+       test_found=true
+     fi
+
+     # Check root __tests__ with path structure
+     if ls "__tests__/${file%.ts*}.test."* 2>/dev/null | grep -q .; then
+       test_found=true
+     fi
+
+     if [ "$test_found" = false ]; then
+       echo "⚠️ NO TEST: $file"
+     fi
+   done
+   ```
+
+3. **Generate Coverage Warning Report:**
+
+   ```markdown
+   ### Test Coverage Analysis
+
+   | Source File | Has Test? | Notes |
+   |-------------|-----------|-------|
+   | `src/lib/feature.ts` | ⚠️ No | New file, no test coverage |
+   | `src/lib/utils.ts` | ✅ Yes | `src/lib/utils.test.ts` |
+   | `app/admin/page.tsx` | - | UI component (browser tested) |
+
+   **Coverage:** X/Y changed source files have corresponding tests
+
+   **Warning:** The following new/modified files lack test coverage:
+   - `src/lib/feature.ts` - Consider adding `src/lib/feature.test.ts`
+   ```
+
+4. **Coverage Tier Classification:**
+
+   | Tier | File Pattern | Coverage Recommendation |
+   |------|--------------|------------------------|
+   | **Critical** | `auth/*`, `payment/*`, `security/*`, `middleware/*` | ⚠️ Flag prominently if missing |
+   | **Standard** | `lib/*`, `utils/*`, `api/*`, `server/*` | Note if missing |
+   | **UI/Browser** | `app/**/page.tsx`, `components/*` | Browser testing covers these |
+   | **Config/Types** | `*.config.*`, `types/*`, `*.d.ts` | No test required |
+
+5. **Detection Heuristic for Critical Paths:**
+   ```bash
+   # Flag critical path changes without tests
+   critical=$(echo "$changed" | grep -E 'auth|payment|security|middleware|server-action' || true)
+   if [[ -n "$critical" ]]; then
+     echo "⚠️ CRITICAL PATH CHANGES - test coverage strongly recommended:"
+     echo "$critical"
+   fi
+   ```
+
+6. **Behavior:**
+   - **Warning-only**: Does NOT block test execution
+   - Include coverage analysis in test results report
+   - Recommend adding tests for uncovered critical paths
+   - Note UI files are covered by browser testing (this skill)
+
+**Why this matters:** Catching missing test coverage early:
+- Prevents regressions from shipping untested code
+- Ensures new logic has corresponding test validation
+- Highlights critical paths that need extra scrutiny
 
 ## Decision Point: Feature Implemented or Not?
 
@@ -369,6 +578,13 @@ Create structured test results:
 
 ### 3.2 GitHub Comment
 
+**If orchestrated (SEQUANT_ORCHESTRATOR is set):**
+- Skip posting GitHub comment (orchestrator handles summary)
+- Include test summary in output for orchestrator to capture
+- Let orchestrator aggregate results across phases
+
+**If standalone:**
+
 Draft comment for Issue #<N>:
 
 ```markdown
@@ -436,6 +652,8 @@ If no explicit tests, use AC as test cases:
 
 ## Browser Testing Best Practices
 
+**Reference:** See [Browser Testing Patterns](references/browser-testing-patterns.md) for comprehensive patterns including forms, modals, grids, async content, and troubleshooting.
+
 ### Snapshots vs. Screenshots
 
 **Use `take_snapshot()` when:**
@@ -587,6 +805,33 @@ Both can be used together:
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### State Updates (Standalone Only)
+
+When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
+
+**At skill start:**
+```bash
+npx tsx scripts/state/update.ts start <issue-number> test
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> test
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> test "X/Y tests failed"
+```
+
+**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
+
+---
+
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

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

@@ -17,7 +17,7 @@ allowed-tools:
   - Bash(git worktree list:*)
   - Bash(ls:*)
   - Bash(mkdir:*)
-  - Task(general-purpose)
+  - Agent(sequant-testgen)
 ---
 
 # Test Generation Command
@@ -39,6 +39,116 @@ When invoked as `/testgen <issue-number>`, your job is to:
 - `/testgen 123` - Generate test stubs for issue #123 based on /spec comment
 - `/testgen` - Generate stubs for the most recently discussed issue in conversation
 
+## Token Optimization with Haiku Sub-Agents
+
+**Purpose:** Test stub generation is highly mechanical and benefits from using haiku sub-agents to minimize token cost.
+
+**Pattern:** Use `Agent(subagent_type="sequant-testgen")` for:
+1. Parsing verification criteria from /spec comments
+2. Generating individual test stubs from templates
+3. Writing test file content
+
+**Benefits:**
+- 90% token cost reduction for mechanical generation
+- Faster execution for templated operations
+- Main agent focuses on orchestration and decisions
+
+### Sub-Agent Usage
+
+**Step 1: Parse Verification Criteria (use haiku)**
+
+```javascript
+Agent(subagent_type="sequant-testgen", prompt=`
+Parse the following /spec comment and extract verification criteria.
+
+For each AC, extract:
+- AC number and description
+- Verification method (Unit Test, Integration Test, Browser Test, Manual Test)
+- Test scenario (Given/When/Then)
+- Integration points
+- Assumptions to validate
+
+Return as JSON:
+{
+  "criteria": [
+    {
+      "acNumber": "AC-1",
+      "description": "...",
+      "verificationMethod": "Unit Test",
+      "scenario": { "given": "...", "when": "...", "then": "..." },
+      "integrationPoints": ["..."],
+      "assumptions": ["..."]
+    }
+  ]
+}
+
+/spec comment:
+${specComment}
+`)
+```
+
+**Step 2: Generate Test Stubs (use haiku for each AC)**
+
+```javascript
+// For each AC with Unit Test or Integration Test verification method
+Agent(subagent_type="sequant-testgen", prompt=`
+Generate a Jest test stub for the following verification criteria.
+
+AC: ${ac.acNumber}: ${ac.description}
+Verification Method: ${ac.verificationMethod}
+Test Scenario:
+- Given: ${ac.scenario.given}
+- When: ${ac.scenario.when}
+- Then: ${ac.scenario.then}
+
+Use the template format:
+- Include Given/When/Then as comments
+- Add TODO markers where implementation is needed
+- Include failure path stubs based on the action verb
+- Use throw new Error('Test stub - implement this test')
+
+Return ONLY the test code, no explanation.
+`)
+```
+
+**Step 3: Write Test Files (main agent)**
+
+The main agent handles file operations to ensure proper coordination:
+- Check if files exist (don't overwrite)
+- Create directories if needed
+- Write generated stubs to correct locations
+
+### When to Use Sub-Agents vs Main Agent
+
+| Task | Agent | Reasoning |
+|------|-------|-----------|
+| Parse /spec comment | haiku | Mechanical text extraction |
+| Generate test stub code | haiku | Templated generation |
+| Identify failure scenarios | haiku | Pattern matching |
+| Decide file locations | main | Requires codebase context |
+| Write files | main | File system coordination |
+| Post GitHub comment | main | Session context needed |
+
+### Parallel Sub-Agent Execution
+
+When multiple ACs need test stubs, spawn haiku agents in parallel:
+
+```javascript
+// Spawn all stub generation agents in a single message
+const stubPromises = criteria
+  .filter(ac => ac.verificationMethod === 'Unit Test' || ac.verificationMethod === 'Integration Test')
+  .map(ac => Agent(subagent_type="sequant-testgen", prompt=`Generate test stub for ${ac.acNumber}...`))
+
+// Collect results
+// Main agent writes all files
+```
+
+**Cost savings example:**
+- 5 AC items with Unit Test verification
+- Without haiku: ~50K tokens (main agent generates all)
+- With haiku: ~5K tokens (main orchestrates, haiku generates)
+- Savings: ~90%
+
 ## Workflow
 
 ### Step 1: Read Verification Criteria from GitHub Issue
@@ -562,6 +672,33 @@ Generated with [Claude Code](https://claude.com/claude-code)
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### State Updates (Standalone Only)
+
+When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
+
+**At skill start:**
+```bash
+npx tsx scripts/state/update.ts start <issue-number> testgen
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> testgen
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> testgen "Failed to generate test stubs"
+```
+
+**Note:** `/testgen` is an optional skill that generates test stubs. State tracking is informational - it doesn't block subsequent phases.
+
+---
+
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/dist/src/commands/dashboard.js

@@ -19,7 +19,7 @@ export async function dashboardCommand(options = {}) {
     const port = options.port ?? 3456;
     const shouldOpen = !options.noOpen;
     const verbose = options.verbose ?? false;
-    console.log(chalk.bold("\n📊 Sequant Dashboard\n"));
+    console.log(chalk.bold("\nSequant Dashboard\n"));
     try {
         // Dynamic import to avoid loading dashboard code unless needed
         const { startDashboard } = await import("../../dashboard/server.js");

package/dist/src/commands/doctor.js

@@ -82,7 +82,7 @@ export async function doctorCommand(options = {}) {
                 message: `Outdated: ${versionResult.currentVersion} → ${versionResult.latestVersion} available`,
             });
             // Show remediation steps
-            console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion, versionResult.isLocalInstall)}`));
+            console.log(chalk.yellow(`  !  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion, versionResult.isLocalInstall)}`));
             console.log("");
         }
         else {

package/dist/src/commands/init.js

@@ -67,7 +67,7 @@ async function updateGitignore() {
  * Log a default value being used in non-interactive mode
  */
 function logDefault(label, value) {
-    console.log(chalk.blue(`📦 ${label}: ${value} (default)`));
+    console.log(chalk.blue(`${label}: ${value} (default)`));
 }
 export async function initCommand(options) {
     // Show banner
@@ -106,14 +106,14 @@ export async function initCommand(options) {
     if (wizardRemainingIssues.length > 0 ||
         (options.skipSetup && warnings.length > 0)) {
         if (wizardRemainingIssues.length > 0) {
-            console.log(chalk.yellow("⚠️  Remaining setup issues:\n"));
+            console.log(chalk.yellow("!  Remaining setup issues:\n"));
             for (const issue of wizardRemainingIssues) {
                 console.log(chalk.yellow(`   • ${issue}`));
             }
             console.log();
         }
         else if (warnings.length > 0) {
-            console.log(chalk.yellow("⚠️  Prerequisites:\n"));
+            console.log(chalk.yellow("!  Prerequisites:\n"));
             for (const warning of warnings) {
                 console.log(chalk.yellow(`   • ${warning}`));
             }
@@ -126,7 +126,7 @@ export async function initCommand(options) {
     // Check if already initialized
     const configExists = await fileExists(".claude/settings.json");
     if (configExists && !options.force) {
-        console.log(chalk.yellow("⚠️  Sequant appears to be already initialized (.claude/settings.json exists)"));
+        console.log(chalk.yellow("!  Sequant appears to be already initialized (.claude/settings.json exists)"));
         console.log(chalk.gray("   Use --force to reinitialize\n"));
         if (!skipPrompts) {
             const { proceed } = await inquirer.prompt([
@@ -151,7 +151,7 @@ export async function initCommand(options) {
         const allDetectedStacks = !skipPrompts ? await detectAllStacks() : [];
         if (allDetectedStacks.length > 1 && !skipPrompts) {
             // Multi-stack project detected - show checkbox selection
-            console.log(chalk.blue(`\n🔍 Detected ${allDetectedStacks.length} stacks in this project:`));
+            console.log(chalk.blue(`\nDetected ${allDetectedStacks.length} stacks in this project:`));
             for (const ds of allDetectedStacks) {
                 const location = ds.path ? ` (${ds.path}/)` : " (root)";
                 console.log(chalk.gray(`   • ${STACKS[ds.stack]?.displayName || ds.stack}${location}`));
@@ -258,7 +258,7 @@ export async function initCommand(options) {
     // Detect package manager
     const packageManager = await detectPackageManager();
     if (packageManager) {
-        console.log(chalk.blue(`📦 Package Manager: ${packageManager}`));
+        console.log(chalk.blue(`Package Manager: ${packageManager}`));
     }
     // Get stack config for default dev URL
     const stackConfig = getStackConfig(stack);
@@ -381,14 +381,14 @@ export async function initCommand(options) {
         // Some symlinks may have fallen back to copies
         const fallbacks = symlinkResults.filter((r) => r.fallbackToCopy);
         if (fallbacks.length > 0) {
-            console.log(chalk.yellow("⚠️  Some scripts were copied instead of symlinked:"));
+            console.log(chalk.yellow("!  Some scripts were copied instead of symlinked:"));
             for (const fb of fallbacks) {
                 console.log(chalk.gray(`   ${fb.path}: ${fb.reason}`));
             }
         }
         const skipped = symlinkResults.filter((r) => r.skipped);
         if (skipped.length > 0) {
-            console.log(chalk.yellow("⚠️  Some scripts were skipped (existing files found):"));
+            console.log(chalk.yellow("!  Some scripts were skipped (existing files found):"));
             for (const s of skipped) {
                 console.log(chalk.gray(`   ${s.path}: ${s.reason}`));
             }
@@ -444,7 +444,7 @@ export async function initCommand(options) {
         for (const client of detectedClients) {
             console.log(chalk.gray(`   • ${client.name}`));
         }
-        let addMcp = false;
+        let addMcp;
         if (skipPrompts) {
             // --yes alone skips MCP config; --yes --mcp explicitly opts in
             addMcp = !!options.mcp;
@@ -483,7 +483,7 @@ export async function initCommand(options) {
     // Build prerequisites reminder if there were remaining issues from wizard or warnings
     const hasRemainingIssues = wizardRemainingIssues.length > 0 || warnings.length > 0;
     const prereqReminder = hasRemainingIssues
-        ? `\n${chalk.yellow("⚠️  Remember to install missing dependencies before using issue workflows.")}\n${chalk.gray("   Run 'sequant doctor' to verify your setup.\n")}`
+        ? `\n${chalk.yellow("!  Remember to install missing dependencies before using issue workflows.")}\n${chalk.gray("   Run 'sequant doctor' to verify your setup.\n")}`
         : "";
     // Success message with boxed output
     const nextStepsContent = `${chalk.bold("Next steps:")}

package/dist/src/commands/logs.js

@@ -171,7 +171,7 @@ function filterLogs(logs, options) {
 async function handleRotation(logDir, dryRun) {
     const settings = await getSettings();
     const stats = getLogStats(logDir, settings.run.rotation);
-    console.log(chalk.blue("\n📝 Log Rotation\n"));
+    console.log(chalk.blue("\nLog Rotation\n"));
     console.log(chalk.gray(`  Log directory: ${logDir}`));
     console.log(chalk.gray(`  Current: ${stats.fileCount} files, ${formatBytes(stats.totalSizeBytes)}`));
     console.log(chalk.gray(`  Thresholds: ${settings.run.rotation.maxFiles} files, ${settings.run.rotation.maxSizeMB} MB`));