sequant 1.18.0 → 1.20.0

package/templates/skills/exec/SKILL.md

@@ -12,9 +12,10 @@ allowed-tools:
   - Grep
   - Edit
   - Write
-  # Build and test
+  # Build, lint, and test
   - Bash(npm test:*)
   - Bash(npm run build:*)
+  - Bash(npm run lint:*)
   - Bash(npm install:*)
   - Bash(npx tsc:*)
   # Git operations
@@ -116,9 +117,38 @@ Invocation:
 - `/exec <freeform description>`:
   - Treat the text as a lightweight description + AC if no issue context is available.
 
+## 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 | `exec` |
+| `SEQUANT_ISSUE` | Issue number being processed | `123` |
+| `SEQUANT_WORKTREE` | Path to the feature worktree | `/path/to/worktrees/feature/...` |
+| `SEQUANT_BASE_BRANCH` | Base branch for worktree (if custom) | `feature/dashboard` |
+
+**Behavior when orchestrated (SEQUANT_ORCHESTRATOR is set):**
+
+1. **Skip pre-flight git checks** - The orchestrator has already verified git state
+2. **Skip worktree creation** - Orchestrator creates worktrees before invoking skills
+3. **Use provided worktree path** - Work in `SEQUANT_WORKTREE` instead of creating a new one
+4. **Reduce GitHub comment frequency** - Defer progress updates to the orchestrator
+5. **Trust issue context** - The orchestrator has already fetched and validated issue data
+
+**Behavior when standalone (SEQUANT_ORCHESTRATOR is NOT set):**
+
+- Perform all pre-flight checks
+- Create worktree if needed
+- Post progress updates to GitHub
+- Fetch fresh issue context
+
 ### 0. Pre-flight Check (After Context Restoration)
 
-**CRITICAL:** If continuing from a restored/summarized conversation, verify git state first:
+**Skip this section if `SEQUANT_ORCHESTRATOR` is set** - the orchestrator has already performed these checks.
+
+**CRITICAL:** If continuing from a restored/summarized conversation (standalone mode), verify git state first:
 
 ```bash
 # Check current state - are we in a worktree or main repo?
@@ -134,6 +164,66 @@ git branch -a | grep -i "<issue-number>" || true
 
 **If PR already merged:** The issue may be complete - verify and close if so.
 
+### 0a. Stale Branch Detection (Warning Only)
+
+**Skip this section if `SEQUANT_ORCHESTRATOR` is set** - the orchestrator handles branch freshness checks.
+
+**Purpose:** Warn when starting implementation on a feature branch that is significantly behind main. This helps developers rebase early rather than discovering conflicts late in the workflow.
+
+**Note:** Unlike `/qa` and `/test`, `/exec` **warns but does not block** — starting implementation on a slightly stale branch is acceptable since rebasing can happen before PR creation.
+
+**Detection:**
+
+```bash
+# Ensure we have latest remote state
+git fetch origin 2>/dev/null || true
+
+# Count commits behind main (only if we're in a worktree, not on main)
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+if [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
+  behind=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo "0")
+  echo "Feature branch is $behind commits behind main"
+fi
+```
+
+**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 | ℹ️ **Info:** "Feature branch is N commits behind main." |
+| > threshold | ⚠️ **Warning:** "Feature branch is N commits behind main (threshold: T). Consider rebasing before continuing: `git fetch origin && git rebase origin/main`" |
+
+**Important:** `/exec` never blocks on stale branches. It warns to help developers make informed decisions about rebasing.
+
+**Output Format:**
+
+```markdown
+### Stale Branch Check
+
+| Check | Value |
+|-------|-------|
+| Commits behind main | N |
+| Threshold | T |
+| Status | ✅ OK / ℹ️ Info / ⚠️ Warning |
+
+[Info/warning message if applicable]
+```
+
 ### 1. Check Implementation Readiness
 
 **FIRST STEP:** Review the issue readiness and proceed with implementation.
@@ -160,34 +250,263 @@ git branch -a | grep -i "<issue-number>" || true
 - Issue is already closed
 - No acceptance criteria exist and cannot be inferred
 
-### 2. Re-establish Context
+### 2. Re-establish Context (with Parallel Optimization)
+
+**Performance Optimization:** When creating a new worktree, gather context in parallel with worktree creation to reduce setup time by ~5-10 seconds.
+
+#### Parallel Context Gathering Pattern
+
+When worktree creation is needed (standalone mode, no existing worktree):
+
+```
+1. Start worktree creation in background    → runs ~30s (npm install)
+2. While waiting, gather context in parallel:
+   - Fetch issue details                    ~2s
+   - Read all issue comments                ~2s
+   - Check for existing patterns/files      ~2s
+3. Wait for worktree completion
+4. Begin implementation with full context ready
+```
+
+**Implementation:**
+
+1. **Start worktree creation as background task:**
+   ```bash
+   # From main repo, start worktree creation in background
+   ./scripts/dev/new-feature.sh <issue-number> &
+   WORKTREE_PID=$!
+   echo "Worktree creation started (PID: $WORKTREE_PID)"
+   ```
+
+2. **Gather context while waiting:**
+   - **Read all GitHub issue comments** to gather complete context:
+     - Comments often contain clarifications, updates, or additional AC added after the initial issue description
+     - Look for discussion about implementation details, edge cases, or requirements mentioned in comments
+     - Review feedback from previous implementation cycles or review comments
+   - Summarize briefly:
+     - The AC checklist (AC-1, AC-2, ...) from the issue and all comments
+     - The current implementation plan (from issue comments or `/spec`)
+     - **The Feature Quality Planning section** (if present from `/spec`)
+   - If there is no plan:
+     - Ask whether to quickly propose one (or suggest using `/spec` first).
+
+#### 2.1b Quality Plan Reference (RECOMMENDED)
+
+**If `/spec` was run**, look for the **Feature Quality Planning** section in issue comments. This section provides guidance for implementation quality:
+
+**What to extract from Quality Plan:**
+- **Error Handling items** → Implement error handling for identified scenarios
+- **Edge cases** → Handle edge cases listed in the plan
+- **Test Coverage items** → Know what tests are expected
+- **Derived ACs** → Additional ACs generated from quality planning
+
+**How to use during implementation:**
+1. Before implementing each AC, check if quality plan has related items
+2. Implement error handling per quality plan's "Error Handling" checklist
+3. Ensure test coverage matches quality plan's "Test Coverage Plan"
+4. Address derived ACs alongside original ACs
+
+**Example reference:**
+```markdown
+Per Quality Plan:
+- Error Handling: Handle API timeout with graceful fallback
+- Test Coverage: Add unit tests for edge case (empty input)
+- Derived AC-6: Log errors for observability
+```
+
+**If no Quality Plan found:** Proceed with standard implementation but note in progress update that quality planning was not available.
+
+#### 2.1b2 Codebase Conventions (RECOMMENDED)
+
+**Before generating code**, check for codebase conventions detected during `sequant init`:
+
+```bash
+# Read conventions file if it exists
+cat .sequant/conventions.json 2>/dev/null || echo "No conventions detected"
+```
+
+**If `.sequant/conventions.json` exists**, use the detected conventions to align generated code:
+- **testFilePattern** → Name test files accordingly (e.g., `*.test.ts` vs `*.spec.ts`)
+- **exportStyle** → Use named or default exports to match codebase style
+- **asyncPattern** → Prefer async/await or promise chains as appropriate
+- **indentation** → Match existing indentation style
+- **semicolons** → Include or omit semicolons per convention
+
+**Manual overrides** in the `manual` section take precedence over detected values.
+
+**If no conventions file exists:** Proceed normally — conventions are optional enhancement.
+
+#### 2.1c Derived AC Extraction (REQUIRED when Quality Plan exists)
+
+**Purpose:** Extract derived ACs from the spec comment's Derived ACs table so they can be tracked alongside original ACs during implementation.
+
+**When to extract:** If the Quality Plan section exists and contains a "Derived ACs" table.
+
+**Extraction Method:**
+
+```bash
+# Extract derived ACs from spec comment's Derived ACs table
+# Format: | Source | AC-N: Description | Priority |
+# Uses flexible pattern to match any source dimension (not hardcoded)
+derived_acs=$(gh issue view <issue-number> --comments --json comments -q '.comments[].body' | \
+  grep -E '\|[^|]+\|\s*AC-[0-9]+:' | \
+  grep -oE 'AC-[0-9]+:[^|]+' | \
+  sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | \
+  sort -u || true)
+
+# Display extracted derived ACs
+if [[ -n "$derived_acs" ]]; then
+  echo "Derived ACs found:"
+  echo "$derived_acs"
+else
+  echo "No derived ACs found in spec comment"
+fi
+```
+
+**Handling Malformed Rows:**
+
+The extraction pattern is designed to handle edge cases:
+- Missing columns → Row is skipped (requires Source + AC-N pattern)
+- Extra whitespace → Trimmed during extraction
+- Empty description → AC ID still captured
+- Non-standard source names → Row is skipped (only standard sources matched)
+
+**Include in AC Tracking:**
+
+Once extracted, derived ACs should be:
+1. Added to the implementation checklist
+2. Tracked in the Pre-PR AC Verification table (labeled as "Derived")
+3. Included in progress updates
+
+**Example Output:**
+
+```markdown
+## Derived ACs (from Quality Plan)
+
+| AC | Source | Description | Status |
+|----|--------|-------------|--------|
+| AC-6 | Error Handling | Handle malformed table rows gracefully | ⬜ Pending |
+| AC-7 | Test Coverage | Verify extraction with 0, 1, 5+ derived ACs | ⬜ Pending |
+```
+
+**If no Derived ACs found:** Output: "Derived ACs: None in spec comment" and proceed with original ACs only.
+
+3. **Wait for worktree completion before implementation:**
+   ```bash
+   # Wait for worktree creation to complete
+   wait $WORKTREE_PID
+   WORKTREE_EXIT=$?
+   if [ $WORKTREE_EXIT -ne 0 ]; then
+     echo "ERROR: Worktree creation failed with exit code $WORKTREE_EXIT"
+     # Fall back to sequential creation with error visibility
+   fi
+   ```
+
+**When to use parallel context gathering:**
+- ✅ Creating a new worktree (standalone mode)
+- ❌ Worktree already exists (skip - just navigate to it)
+- ❌ Orchestrated mode (SEQUANT_WORKTREE set - worktree pre-created)
+
+**Fallback:** If parallel execution fails or is not applicable, fall back to sequential context gathering.
+
+### 2.1a Smoke Test (Recommended for UI Issues)
+
+**Purpose:** Catch runtime failures that pass `npm test` and `npm run build` but crash at runtime (e.g., missing module registrations, framework version incompatibilities).
+
+**When to run:** Issues with `admin`, `ui`, or `frontend` labels.
+
+**Skip if:** Issue has none of these labels (backend-only, CLI, docs, etc.).
+
+**Quick verification (< 30 seconds):**
+
+1. Start dev server in background:
+   ```bash
+   npm run dev &
+   DEV_PID=$!
+   sleep 5  # Wait for server startup
+   ```
+
+2. Check for startup errors:
+   ```bash
+   # Verify server is running
+   curl -s http://localhost:3000 > /dev/null && echo "✓ Server responding" || echo "✗ Server not responding"
+   ```
+
+3. Kill the dev server:
+   ```bash
+   kill $DEV_PID 2>/dev/null
+   ```
+
+**What to look for:**
+- ✗ Server crash on startup → Check `framework-gotchas.md`
+- ✗ Blank white page → React hydration error or missing component
+- ✗ Module registration errors → AG Grid, chart libraries, etc.
+- ✗ Console errors on load → Missing imports, env vars
 
-- **Read all GitHub issue comments** to gather complete context:
-  - Comments often contain clarifications, updates, or additional AC added after the initial issue description
-  - Look for discussion about implementation details, edge cases, or requirements mentioned in comments
-  - Review feedback from previous implementation cycles or review comments
-- Summarize briefly:
-  - The AC checklist (AC-1, AC-2, ...) from the issue and all comments
-  - The current implementation plan (from issue comments or `/spec`)
-- If there is no plan:
-  - Ask whether to quickly propose one (or suggest using `/spec` first).
+**If issues found:** Fix before proceeding with new implementation. Reference `references/shared/framework-gotchas.md` for common solutions.
 
 ### Feature Worktree Workflow
 
 **Execution Phase:** Create and work in a feature worktree.
 
+**CRITICAL: Main Branch Safeguard (Issue #85)**
+
+Before starting any implementation, verify you are NOT on the main/master branch:
+
+```bash
+# Check current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "Current branch: $CURRENT_BRANCH"
+```
+
+**If on main/master branch:**
+1. **STOP** - Do not implement directly on main
+2. Create a feature worktree first: `./scripts/dev/new-feature.sh <issue-number>`
+   - For custom base branch: `./scripts/dev/new-feature.sh <issue-number> --base <branch>`
+3. Navigate to the worktree before making any changes
+
+**Why this matters:** Work done directly on main can be lost during sync operations (git reset, git pull --rebase, etc.). Worktrees provide isolation and safe recovery through branches.
+
+**If orchestrated (SEQUANT_WORKTREE is set):**
+- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
+- Skip steps 1-2 below (worktree already created by orchestrator)
+- Continue with step 3 (Work in the worktree)
+
+**If standalone:**
+
 1. **Check if worktree already exists:**
    - Check if you're already in a worktree: `git worktree list` or check if `../worktrees/` contains a directory for this issue
    - If worktree exists, navigate to it and continue work there
 
-2. **Create worktree if needed:**
-   - From the main repository directory, run: `./scripts/dev/new-feature.sh <issue-number>`
-   - This will:
+2. **Create worktree if needed (with parallel context gathering):**
+
+   **Optimized flow (parallel):**
+   ```bash
+   # Step 1: Start worktree creation in background
+   # For default (main) base:
+   ./scripts/dev/new-feature.sh <issue-number> &
+   # For custom base branch (e.g., feature integration branch):
+   ./scripts/dev/new-feature.sh <issue-number> --base feature/dashboard &
+   WORKTREE_PID=$!
+
+   # Step 2: Gather context while worktree creates (see Section 2)
+   # - Fetch issue details
+   # - Read issue comments
+   # - Check for existing patterns
+
+   # Step 3: Wait for worktree completion
+   wait $WORKTREE_PID
+   ```
+
+   **What new-feature.sh does:**
      - Fetch issue details from GitHub
      - Create branch: `feature/<issue-number>-<issue-title-slug>`
      - Create worktree in: `../worktrees/feature/<branch-name>/`
-     - Install dependencies
+     - Branch from specified base (default: main)
+     - Install dependencies (can use cache if `SEQUANT_NPM_CACHE=true`)
      - Copy environment files if they exist
+
+   **After completion:**
    - Navigate to the worktree directory: `cd ../worktrees/feature/<branch-name>/`
 
 3. **Work in the worktree:**
@@ -202,6 +521,204 @@ git branch -a | grep -i "<issue-number>" || true
 
 **Important:** Always work in the worktree directory, not the main repository, once the worktree is created.
 
+### Pre-PR AC Verification (REQUIRED)
+
+**Before creating a PR**, you MUST verify that each Acceptance Criteria has been addressed:
+
+1. **Retrieve AC from workflow state:**
+   ```bash
+   # Get stored AC for this issue
+   npx tsx -e "
+   import { StateManager } from './src/lib/workflow/state-manager.ts';
+   const manager = new StateManager();
+   (async () => {
+     const state = await manager.getIssueState(<issue-number>);
+     if (state?.acceptanceCriteria) {
+       console.log(JSON.stringify(state.acceptanceCriteria, null, 2));
+     } else {
+       console.log('No AC found in state - check issue body');
+     }
+   })();
+   "
+   ```
+
+2. **If no AC in state**, extract from issue body:
+   - Check issue body for AC items (AC-1, AC-2, etc.)
+   - Parse from issue comments if clarifications were added
+
+3. **Generate AC Verification Checklist:**
+
+   For each AC item (including derived ACs), determine implementation status:
+
+   ```markdown
+   ### Pre-PR AC Verification
+
+   | AC | Source | Description | Status | Evidence |
+   |----|--------|-------------|--------|----------|
+   | AC-1 | Original | [Description] | ✅ Implemented | [File:line or brief explanation] |
+   | AC-2 | Original | [Description] | ✅ Implemented | [File:line or brief explanation] |
+   | AC-3 | Original | [Description] | ⚠️ Partial | [What's missing] |
+   | **Derived ACs** | | | | |
+   | AC-6 | Error Handling | [From Quality Plan] | ✅ Implemented | [File:line] |
+   | AC-7 | Test Coverage | [From Quality Plan] | ⚠️ Partial | [What's missing] |
+   ```
+
+   **Derived AC Handling:**
+   - Extract derived ACs using the method in Section 2.1c
+   - Include in the same verification table with "Source" column indicating origin
+   - Treat derived ACs identically to original ACs for verification purposes
+
+4. **Status Definitions:**
+   - ✅ **Implemented**: Code exists that satisfies this AC
+   - ⚠️ **Partial**: Some aspects implemented, others missing
+   - ❌ **Not addressed**: AC not implemented (must include justification)
+   - 🔄 **Deferred**: Intentionally deferred to follow-up issue (link issue)
+
+5. **Verification Behavior:**
+   - **All AC ✅**: Proceed to PR creation
+   - **Some AC ⚠️/❌**: Include in PR description as known gaps
+   - **Critical AC ❌**: Consider whether to create PR or continue implementation
+
+6. **Include in PR Description:**
+   Add the AC verification table to the PR body so reviewers can validate coverage.
+
+**Why this matters:** Catching AC gaps before PR creation:
+- Reduces review cycles
+- Ensures nothing is forgotten
+- Documents intentional deferrals
+- Enables better QA in `/qa` phase
+
+### 3f. CHANGELOG Update (REQUIRED for user-facing changes)
+
+**Purpose:** Ensure all user-facing changes are documented in the CHANGELOG before PR creation. This prevents documentation gaps and reduces release overhead.
+
+**When to update CHANGELOG:**
+
+| Change Type | CHANGELOG Required? | Section |
+|-------------|---------------------|---------|
+| New feature | ✅ Yes | `### Added` |
+| Bug fix | ✅ Yes | `### Fixed` |
+| Breaking change | ✅ Yes | `### Changed` or `### Removed` |
+| Performance improvement | ✅ Yes | `### Changed` |
+| Dependency update (security) | ✅ Yes | `### Fixed` or `### Security` |
+| Documentation only | ❌ No | - |
+| Internal refactor (no behavior change) | ❌ No | - |
+| Test-only changes | ❌ No | - |
+| CI/workflow changes | ❌ No | - |
+
+**How to update:**
+
+1. **Check if CHANGELOG.md exists:**
+   ```bash
+   if [ -f "CHANGELOG.md" ]; then
+     echo "CHANGELOG.md found - update required for user-facing changes"
+   else
+     echo "No CHANGELOG.md - skip CHANGELOG update"
+   fi
+   ```
+
+2. **If CHANGELOG.md exists and change is user-facing**, use the Edit tool to add an entry under `## [Unreleased]`:
+
+   ```markdown
+   ## [Unreleased]
+
+   ### Added
+
+   - Brief description of new feature (#<issue-number>)
+   ```
+
+3. **Entry format:**
+   - Start with a verb: "Add", "Fix", "Update", "Remove", "Improve"
+   - Keep it concise (1-2 lines)
+   - Include issue number as `(#123)`
+   - Group related changes in a single bullet with sub-bullets if needed
+
+**Example entries:**
+
+```markdown
+### Added
+
+- CHANGELOG update step in /exec skill (#320)
+  - Instructs /exec to add [Unreleased] entries during feature commits
+  - Includes change type classification table
+
+### Fixed
+
+- Race condition in parallel agent spawning (#315)
+```
+
+**If CHANGELOG doesn't exist:** Skip this step. Not all projects use CHANGELOG.md.
+
+**If change is not user-facing:** Skip this step but note in progress summary: "CHANGELOG: N/A (internal change)"
+
+---
+
+### 3g. CLI Wiring Checklist (When Option Interfaces Modified)
+
+**Purpose:** Prevent incomplete CLI implementations where option interface fields are added but never wired to CLI flags. This is a proactive check during implementation, complementing the verification in `/qa`.
+
+**When to apply:** Adding or modifying `RunOptions` or similar CLI option interfaces.
+
+**Origin:** Issue #305 — A `force` option was added to `RunOptions` and used in runtime logic, but `--force` was never registered in `bin/cli.ts`. This caused the feature to be unreachable by users.
+
+**Before committing changes that add option interface fields:**
+
+| Step | Action | Verification |
+|------|--------|--------------|
+| 1 | Add field to interface | `src/lib/workflow/batch-executor.ts` |
+| 2 | Register CLI flag | Add `.option("--flag-name", "description")` in `bin/cli.ts` |
+| 3 | Wire to handler | Ensure `options.flagName` passes to implementation |
+| 4 | Test CLI help | Run `npx tsx bin/cli.ts <command> --help` to verify flag appears |
+
+**Key File Map:**
+
+| Interface | Location | CLI Registration |
+|-----------|----------|------------------|
+| `RunOptions` | `src/lib/workflow/batch-executor.ts` | `run` command in `bin/cli.ts` |
+
+**Quick Verification Script:**
+
+```bash
+# List all RunOptions fields
+grep -E '^\s+\w+\??: ' src/lib/workflow/batch-executor.ts | head -30 || true
+
+# List all registered options for 'run' command
+grep -A 50 'command("run")' bin/cli.ts | grep '\.option(' | head -30 || true
+
+# Check if a specific field is registered (e.g., 'force')
+field_name="force"
+cli_flag=$(echo "$field_name" | sed 's/\([A-Z]\)/-\L\1/g')  # camelCase to kebab-case
+grep -q "\-\-$cli_flag" bin/cli.ts && echo "✅ --$cli_flag registered" || echo "❌ --$cli_flag NOT registered"
+```
+
+**Internal-only Field Exclusion:**
+
+Not all interface fields need CLI registration. Fields are internal-only if:
+- They have no `mergedOptions.X` runtime usage (set programmatically)
+- They're environment-controlled (e.g., `SEQUANT_*` env vars)
+- They're only used in type signatures, not at runtime
+
+**Detection:** If `grep "mergedOptions.$field"` returns no matches, the field is likely internal-only.
+
+**Self-Check Before Commit:**
+
+```markdown
+## CLI Wiring Self-Check
+
+| New Field | CLI Flag | Help Text | Wiring Status |
+|-----------|----------|-----------|---------------|
+| `newOption` | `--new-option` | "Description" | ✅ Complete |
+| `internalOnly` | N/A | N/A | ⏭️ Internal |
+```
+
+**If wiring is incomplete:**
+1. Add the missing `.option()` call in `bin/cli.ts`
+2. Update help text to describe the flag
+3. Run `npm run build` to verify no TypeScript errors
+4. Test with `--help` to confirm flag appears
+
+---
+
 ### PR Creation and Verification
 
 After implementation is complete and all checks pass, create and verify the PR:
@@ -244,6 +761,16 @@ After implementation is complete and all checks pass, create and verify the PR:
    - If PR exists: Record the URL from `gh pr view` output
    - If PR creation failed: Record the error and include manual creation instructions
 
+6. **Record PR info in workflow state:**
+   ```bash
+   # Extract PR number and URL from gh pr view output, then update state
+   PR_INFO=$(gh pr view --json number,url)
+   PR_NUMBER=$(echo "$PR_INFO" | jq -r '.number')
+   PR_URL=$(echo "$PR_INFO" | jq -r '.url')
+   npx tsx scripts/state/update.ts pr <issue-number> "$PR_NUMBER" "$PR_URL"
+   ```
+   This enables `--cleanup` to detect merged PRs and auto-remove state entries.
+
 **PR Verification Failure Handling:**
 
 If `gh pr view` fails after retry:
@@ -275,6 +802,52 @@ If `gh pr view` fails after retry:
 - If it needs modification, extend it rather than creating a new one
 - Document why existing utilities don't meet requirements before creating new ones
 
+### Check npm for Existing Packages
+
+**IMPORTANT:** Before implementing utilities for common "solved problem" domains, check if a well-maintained package exists.
+
+**Domains to check npm first:**
+
+| Domain | Recommended Packages |
+|--------|---------------------|
+| Date/time handling | `date-fns`, `dayjs` |
+| Validation | `zod`, `yup`, `valibot` |
+| HTTP requests with retry | `ky`, `got`, `axios` |
+| Form state | `react-hook-form`, `formik` |
+| State management | `zustand`, `jotai` |
+| ID generation | `nanoid`, `uuid` |
+| String utilities | `lodash` (specific imports only) |
+
+**Package evaluation criteria:**
+
+| Criterion | Threshold | Why |
+|-----------|-----------|-----|
+| Weekly downloads | >10,000 | Indicates community trust |
+| Last update | <6 months ago | Actively maintained |
+| License | MIT, Apache-2.0, BSD | Permissive, compatible |
+| Bundle size | Proportional to use | Avoid 500kb for one function |
+
+**Quick check commands:**
+```bash
+# Package metadata (license, last update, size)
+npm view <pkg> --json | jq '{name, version, license, modified: .time.modified, size: .dist.unpackedSize}'
+
+# Weekly downloads (requires npm API)
+curl -s "https://api.npmjs.org/downloads/point/last-week/<pkg>" | jq '.downloads'
+```
+
+**Custom implementation is appropriate when:**
+- Only a tiny subset of functionality needed (<20 lines)
+- Package is abandoned (no updates 12+ months) or has security issues
+- Project constraints prohibit new dependencies
+- User explicitly requests custom solution
+
+**Decision flow:**
+1. Is this a "solved problem" domain? → Check npm first
+2. Does a well-maintained package exist? → Prefer package
+3. Would custom implementation be <20 lines? → Custom is OK
+4. Uncertain? → Ask user preference
+
 ### Check Framework Gotchas on Runtime Errors
 
 **When encountering unexpected runtime errors or build failures:**
@@ -292,19 +865,41 @@ If you discover a new framework-specific issue that caused debugging time, add i
 
 This section covers optional MCP tools that enhance implementation quality when available.
 
-#### MCP Availability Check
+#### MCP Availability Check (Lazy Loading)
+
+**Performance Optimization:** Check MCP availability lazily on first use, NOT proactively at session start. This avoids wasting time checking MCPs for issues that don't need them.
 
-**Before using MCP tools**, verify they are available in your session. If unavailable, use the documented fallback behavior.
+**Lazy Check Pattern:**
+- ❌ **Don't:** Check all MCPs at session start
+- ✅ **Do:** Check MCP availability only when you're about to use it
 
 ```markdown
-**MCP Status Check (perform at session start):**
-- [ ] Context7: Try `mcp__context7__resolve-library-id` - if available, proceed
-- [ ] Sequential Thinking: Try `mcp__sequential-thinking__sequentialthinking` - if available, proceed
-- [ ] Chrome DevTools: Try `mcp__chrome-devtools__take_snapshot` - if available, proceed
+**MCP Check (on first use only):**
+When you need to use an MCP tool:
+1. Attempt the MCP call
+2. If it fails with "tool not available", use the fallback strategy
+3. Cache the result for the session (don't re-check)
+```
 
-If any MCP is unavailable, use fallback strategies documented below.
+**Example - Lazy Context7 Check:**
+```javascript
+// Only check when you actually need library docs
+// NOT at session start
+if (need_library_documentation) {
+  // Try Context7 - fallback to WebSearch if unavailable
+  try {
+    mcp__context7__resolve-library-id(...)
+  } catch {
+    // Fallback: use WebSearch or codebase patterns
+  }
+}
 ```
 
+**Why lazy loading:**
+- Many issues don't need MCPs (simple bugs, docs, config changes)
+- Proactive checks waste 2-5 seconds per MCP
+- Lazy checks only run when the tool provides value
+
 ---
 
 #### Context7 - Library Documentation Lookup
@@ -462,20 +1057,387 @@ If your project uses a database MCP (e.g., Supabase, Postgres):
 ### 3. Checks-first Mindset
 
 - Before and after meaningful changes, plan to run:
-  - `npm test`
+  - `npm run build` - TypeScript compilation
+  - `npm run lint` - ESLint validation (catches unused imports, formatting issues)
+  - `npm test` - Run relevant tests
 - For larger changes or anything that might impact build/runtime:
   - Suggest running `npm run build` and interpret any errors.
 
+**Pre-PR Quality Gates (REQUIRED):**
+
+Before creating a PR, run ALL checks in this order:
+1. `npm run build` - Must pass (no TypeScript errors)
+2. `npm run lint` - Must pass (no ESLint errors)
+3. `npm test` - Must pass (all tests green)
+
+If any check fails, fix the issues before creating the PR.
+
 Do NOT silently skip checks. Always state which commands you intend to run and why.
 
+### 3a. Test Coverage Transparency (REQUIRED)
+
+**Purpose:** Report which changed files have corresponding tests, not just "N tests passed."
+
+**After running `npm test`, you MUST analyze test coverage for changed files:**
+
+Use the Glob tool to check for corresponding test files:
+```
+# Get changed source files (excluding tests) from git
+changed=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$' | grep -v -E '\.test\.|\.spec\.|__tests__' || true)
+
+# For each changed file, use the Glob tool to find matching test files
+# Glob(pattern="**/${base}.test.*") or Glob(pattern="**/${base}.spec.*")
+# If no test file found, report "NO TEST: $file"
+```
+
+**Required reporting format:**
+
+| Scenario | Report |
+|----------|--------|
+| Tests cover changed files | `Tests: N passed (covers changed files)` |
+| Tests don't cover changed files | `Tests: N passed (⚠️ 0 cover changed files)` |
+| No tests for specific files | `Tests: N passed (⚠️ NO TESTS: file1.ts, file2.ts)` |
+
+### 3b. Change Tier Classification
+
+**Purpose:** Flag coverage gaps based on criticality, not just presence/absence.
+
+**Tier definitions:**
+
+| Tier | Change Type | Coverage Requirement |
+|------|-------------|---------------------|
+| **Critical** | Auth, payments, security, server-actions, middleware, admin | Flag prominently if missing |
+| **Standard** | Business logic, API handlers, utilities | Note if missing |
+| **Optional** | Config, types-only, UI tweaks | No flag needed |
+
+**Detection heuristic:**
+
+```bash
+# Detect critical paths in changed files
+changed=$(git diff main...HEAD --name-only | grep -E '\.(ts|tsx|js|jsx)$' || true)
+critical=$(echo "$changed" | grep -E 'auth|payment|security|server-action|middleware|admin' || true)
+
+if [[ -n "$critical" ]]; then
+  echo "⚠️ CRITICAL PATH CHANGES (test coverage strongly recommended):"
+  echo "$critical"
+fi
+```
+
+**Include in progress summary:**
+
+```markdown
+### Test Coverage Analysis
+
+| Changed File | Tier | Has Tests? |
+|--------------|------|------------|
+| `auth/login.ts` | Critical | ⚠️ NO TESTS |
+| `lib/utils.ts` | Standard | ✅ Yes |
+| `types/index.ts` | Optional | - (types only) |
+
+**Coverage:** X/Y changed source files have corresponding tests
+```
+
+### 3c. Shell Script Checks (When .sh files modified)
+
+**Purpose:** Catch shell script issues that `npm test` and `npm run build` miss.
+
+**When shell scripts are modified, run these checks:**
+
+```bash
+# Get changed shell scripts
+shell_scripts=$(git diff main...HEAD --name-only | grep -E '\.sh$' || true)
+
+for script in $shell_scripts; do
+  echo "Checking: $script"
+
+  # 1. Syntax validation
+  bash -n "$script" && echo "✅ Syntax OK" || echo "❌ Syntax error"
+
+  # 2. Shellcheck (if available)
+  if command -v shellcheck &>/dev/null; then
+    shellcheck "$script" && echo "✅ Shellcheck OK" || echo "⚠️ Shellcheck warnings"
+  fi
+
+  # 3. Unused function detection
+  funcs=$(grep -oE "^[a-zA-Z_]+\(\)" "$script" | sed 's/()//' || true)
+  for func in $funcs; do
+    calls=$(grep -c "\b${func}\b" "$script" || echo "0")
+    if [[ $calls -lt 2 ]]; then
+      echo "⚠️ Function '$func' defined but possibly not called"
+    fi
+  done
+
+  # 4. Smoke test (--help or similar)
+  if grep -q "getopts\|--help" "$script"; then
+    bash "$script" --help 2>/dev/null && echo "✅ --help works" || echo "⚠️ --help failed"
+  fi
+done
+```
+
+**Checklist:**
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Syntax | `bash -n script.sh` | Exit code 0 |
+| Shellcheck | `shellcheck script.sh` | No errors (warnings OK) |
+| Functions used | grep analysis | All defined functions called |
+| Smoke test | `bash script.sh --help` | Runs without crash |
+
+**Include in progress summary:**
+
+```markdown
+### Shell Script Checks
+
+| Script | Syntax | Shellcheck | Functions | Smoke Test |
+|--------|--------|------------|-----------|------------|
+| `quality-checks.sh` | ✅ OK | ⚠️ 2 warnings | ✅ All used | ✅ OK |
+```
+
+### 3d. Lint Check (REQUIRED before PR)
+
+**Purpose:** Catch ESLint errors locally before they fail CI. This prevents wasted quality loop iterations from lint failures.
+
+**When to run:** Before every PR creation. Run after `npm run build` succeeds, before `npm test`.
+
+**Execution:**
+
+```bash
+# Run lint check
+npm run lint
+
+# If lint script doesn't exist, gracefully skip
+if ! npm run lint 2>/dev/null; then
+  if npm run --list 2>/dev/null | grep -q "lint"; then
+    echo "❌ Lint failed - fix issues before PR"
+    # Show specific errors
+    npm run lint 2>&1 | head -50
+  else
+    echo "ℹ️ No lint script found - skipping lint check"
+  fi
+fi
+```
+
+**Graceful Skip Logic (AC-4):**
+
+Not all projects have a lint script. Handle this gracefully:
+
+| Scenario | Behavior |
+|----------|----------|
+| `npm run lint` passes | ✅ Continue to tests |
+| `npm run lint` fails with errors | ❌ Fix errors before PR |
+| No `lint` script in package.json | ⚠️ Skip lint, log "No lint script found" |
+| Lint script exists but times out | ⚠️ Log warning, continue |
+
+**Detection of lint script:**
+
+```bash
+# Check if lint script exists
+if npm run --list 2>/dev/null | grep -qE "^\s*lint\b"; then
+  echo "Lint script found - running npm run lint"
+  npm run lint
+else
+  echo "ℹ️ No lint script in package.json - skipping lint check"
+fi
+```
+
+**If lint fails:**
+
+1. **Read the error output** - identify which files/lines have issues
+2. **Common lint errors to fix:**
+   - Unused imports → Remove them
+   - Unused variables → Remove or use them
+   - Missing semicolons → Add them (if required by config)
+   - Formatting issues → Run auto-fix if available
+3. **Fix the issues** - make minimal changes
+4. **Re-run lint** - verify all errors are resolved
+5. **Then continue** - to `npm test`
+
+**Auto-fix consideration:**
+
+Some projects support `npm run lint -- --fix`. However, auto-fix should be used cautiously:
+- ✅ Safe: formatting fixes, import ordering
+- ⚠️ Caution: removing unused code (verify it's truly unused)
+- ❌ Avoid: auto-fixing semantic errors without review
+
+**Include in progress summary:**
+
+```markdown
+### Lint Results
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| ESLint | ✅ Passed | 0 errors, 0 warnings |
+```
+
+Or if issues were found and fixed:
+
+```markdown
+### Lint Results
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| ESLint | ✅ Passed (after fixes) | Fixed 2 unused imports in `src/lib/scope/index.ts` |
+```
+
+### 3e. Testing Non-Exported Functions (REQUIRED)
+
+**Purpose:** Provide guidance when a function needs tests but is not exported, preventing tautological tests that provide zero regression protection.
+
+**Decision Tree:**
+
+```
+Function needs tests but is not exported?
+│
+├─ Can it be exported with @internal tag?
+│   └─ YES → Export it, test directly
+│
+├─ Can a dependency be injected for mocking?
+│   └─ YES → Add optional param, test with mock
+│
+├─ Can the behavior be tested via a public caller?
+│   └─ YES → Write integration test through the public API
+│
+└─ None of the above?
+    └─ Document why tests are limited, do NOT write tautological tests
+```
+
+**⚠️ ANTI-PATTERN WARNING:**
+
+> **NEVER write tests that only assert on local variables.** If a test block does not call any imported function, it is tautological and provides no regression protection.
+>
+> **Bad example (from #267):**
+> ```typescript
+> // ❌ TAUTOLOGICAL - tests nothing real
+> it("should retry on failure", () => {
+>   const mcpEnabled = true;
+>   const phaseFailed = true;
+>   expect(mcpEnabled && phaseFailed).toBe(true); // Always passes!
+> });
+> ```
+>
+> If you cannot test a function directly, escalate to integration testing or export with `@internal` — **do not fake the test**.
+
+**Pattern 1: Export with @internal**
+
+When the function can be safely exported without breaking encapsulation:
+
+```typescript
+// src/lib/retry.ts
+
+/** @internal Exported for testing only - do not use directly */
+export function executePhaseWithRetry(
+  phase: Phase,
+  maxRetries: number,
+): Promise<Result> {
+  // Implementation
+}
+
+// src/lib/retry.test.ts
+import { executePhaseWithRetry } from './retry';
+
+it("retries up to maxRetries on failure", async () => {
+  const result = await executePhaseWithRetry(mockPhase, 3);
+  expect(result.attempts).toBe(3);
+});
+```
+
+**Pattern 2: Dependency Injection (often combined with Pattern 1)**
+
+When the function has internal dependencies that need mocking, DI requires the
+function to be exported so tests can pass in mock dependencies. Combine with
+`@internal` from Pattern 1 to signal it's not part of the public API:
+
+```typescript
+// src/lib/retry.ts
+
+/** @internal Exported for testing - DI allows mocking internal dependencies */
+export function retry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number,
+  // Injectable for tests - defaults to real implementation
+  delayFn: (ms: number) => Promise<void> = delay,
+): Promise<T> {
+  // Implementation uses delayFn instead of hardcoded delay
+}
+
+// src/lib/retry.test.ts
+import { retry } from './retry';
+
+it("waits between retries", async () => {
+  const mockDelay = vi.fn().mockResolvedValue(undefined);
+
+  await retry(failingFn, 3, mockDelay);
+
+  expect(mockDelay).toHaveBeenCalledTimes(2); // Called between retries
+});
+```
+
+**Pattern 3: Integration Test via Public API**
+
+When the private function is called by a public entry point:
+
+```typescript
+// src/commands/run.ts (public)
+export async function runCommand(options: RunOptions): Promise<Result> {
+  // Internally calls executePhaseWithRetry (private)
+}
+
+// src/commands/run.test.ts
+import { runCommand } from './run';
+
+it("retries on cold-start MCP failure", async () => {
+  // Mock the MCP to fail once then succeed
+  mockMcp.onFirstCall().throws(new Error("Cold start"));
+  mockMcp.onSecondCall().resolves(successResult);
+
+  // Test via public API - exercises the private retry logic
+  const result = await runCommand({ useMcp: true });
+
+  expect(result.exitCode).toBe(0);
+  expect(mockMcp.callCount).toBe(2); // Proves retry happened
+});
+```
+
+**Pattern 4: Document Limitation (Last Resort)**
+
+When none of the above approaches work, document the limitation clearly:
+
+```typescript
+// src/lib/internal.ts
+
+/**
+ * @remarks
+ * This function cannot be directly tested because:
+ * - It relies on process-level state that cannot be mocked
+ * - Exporting would break the module's encapsulation contract
+ * - No public API exercises this code path in isolation
+ *
+ * Coverage is provided indirectly through E2E tests in:
+ * - e2e/full-workflow.test.ts (lines 45-67)
+ *
+ * TODO: Refactor to enable direct testing (see #XXX)
+ */
+function internalHelper(): void {
+  // Implementation
+}
+```
+
+**When documenting limitations, you MUST:**
+1. Explain WHY direct testing is not possible
+2. Reference any indirect coverage (E2E, integration tests)
+3. Create a follow-up issue if refactoring would enable testability
+4. **Never** write a tautological test to inflate coverage numbers
+
 ### 4. Implementation Loop
 
 - Implement in **small, incremental diffs**.
 - Prefer touching the minimal number of files required.
 - Align with repository conventions described in CLAUDE.md (naming, patterns, etc.).
 - After each meaningful change:
-  1. Run `npm test` (and optionally `npm run build`).
-  2. If checks fail:
+  1. Run `npm run build` (if TypeScript changes)
+  2. Run `npm run lint` (catches unused imports early)
+  3. Run `npm test`
+  4. If checks fail:
      - Inspect the failure output.
      - Identify the root cause.
      - Apply small, targeted fixes.
@@ -547,7 +1509,9 @@ Fall back to sequential execution (standard implementation loop).
 - Run Prettier on all modified files after each group (agents skip auto-format)
 - On any agent failure: stop remaining agents, log error, continue with sequential
 - File locking prevents concurrent edits to the same file
-- **Use prompt templates** for each agent — see [Section 4c](#4c-prompt-templates-for-sub-agents)
+- **REQUIRED:** When spawning agents, you MUST use prompt templates from Section 4c for typed tasks (component, CLI, test, refactor). Generic prompts are only acceptable for truly untyped tasks.
+
+⚠️ **Warning:** Skipping templates for typed tasks will result in QA rejection.
 
 **Error Handling with Automatic Retry:**
 
@@ -746,7 +1710,49 @@ When in doubt, choose:
 
 The goal is to satisfy AC with the smallest, safest change possible.
 
-### 5. Progress Summary and Draft Issue Update
+### 5. Adversarial Self-Evaluation (REQUIRED)
+
+**Before outputting your final summary**, you MUST complete this adversarial self-evaluation to catch issues that automated checks miss.
+
+**Why this matters:** Sessions show that honest self-questioning consistently catches real issues:
+- Tests that pass but don't cover the actual changes
+- Features that build but don't work as expected
+- AC items marked "done" but with weak implementation
+
+**Answer these questions honestly:**
+1. "Did anything not work as expected during implementation?"
+2. "If this feature broke tomorrow, would the current tests catch it?"
+3. "What's the weakest part of this implementation?"
+4. "Am I reporting success metrics without honest self-evaluation?"
+
+**Include this section in your output:**
+
+```markdown
+### Self-Evaluation
+
+- **Worked as expected:** [Yes/No - if No, explain what didn't work]
+- **Test coverage confidence:** [High/Medium/Low - explain why]
+- **Weakest part:** [Identify the weakest aspect of the implementation]
+- **Honest assessment:** [Any concerns or caveats?]
+```
+
+**If any answer reveals concerns:**
+- Address the issues before proceeding
+- Re-run relevant checks (`npm test`, `npm run build`)
+- Update the self-evaluation after fixes
+
+**Do NOT skip this self-evaluation.** Honest reflection catches issues that automated checks miss.
+
+---
+
+### 6. Progress Summary and Draft Issue Update
+
+**If orchestrated (SEQUANT_ORCHESTRATOR is set):**
+- Skip posting progress comments to GitHub (orchestrator handles summary)
+- Still provide AC coverage summary in output for orchestrator to capture
+- Let orchestrator handle final GitHub update
+
+**If standalone:**
 
 At the end of a session:
 
@@ -761,9 +1767,26 @@ At the end of a session:
    - Include:
      - AC coverage summary
      - Brief list of key files changed
+     - **Quality Plan Alignment** (REQUIRED if quality plan exists in issue comments)
      - **PR Status** (Created with URL, or Failed with reason and manual instructions)
      - Any known gaps or open questions
 
+   **Quality Plan Alignment (REQUIRED when quality plan exists):**
+
+   If the issue has a Feature Quality Planning section from `/spec`, you MUST include this section. If no quality plan exists, output: "Quality Plan Alignment: N/A - No quality plan in issue"
+   ```markdown
+   ### Quality Plan Alignment
+
+   | Quality Dimension | Items Addressed | Notes |
+   |-------------------|-----------------|-------|
+   | Error Handling | 2/3 | Missing: API timeout handling |
+   | Test Coverage | 3/3 | All critical paths covered |
+   | Code Quality | 2/2 | Types defined, patterns followed |
+   | Best Practices | 1/1 | Logging added |
+
+   **Derived ACs:** 2/2 addressed
+   ```
+
    - Label it clearly as:
 
      ```md
@@ -792,13 +1815,47 @@ You may be invoked multiple times for the same issue. Each time, re-establish co
 
 ---
 
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### Check Orchestration Mode
+
+The orchestration check happens automatically when you run the state update script - it exits silently if `SEQUANT_ORCHESTRATOR` is set.
+
+### 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> exec
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> exec
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> exec "Error description"
+```
+
+**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:**
 
+- [ ] **Self-Evaluation Completed** - Adversarial self-evaluation section included in output
 - [ ] **AC Progress Summary** - Which AC items are satisfied, partially met, or blocked
 - [ ] **Files Changed** - List of key files modified
-- [ ] **Test/Build Results** - Output from `npm test` and `npm run build`
+- [ ] **Test/Build/Lint Results** - Output from `npm run build`, `npm run lint`, and `npm test`
+- [ ] **CLI Wiring Check** - If option interfaces modified, verified CLI flags are registered (Section 3g)
+- [ ] **Quality Plan Alignment** - Included if quality plan was available (or marked N/A if no quality plan)
 - [ ] **PR Status** - Created (with URL) or Failed (with error and manual instructions)
 - [ ] **Progress Update Draft** - Formatted comment for GitHub issue
 - [ ] **Documentation Reminder** - Note if README/docs need updating (checked in /qa)