sequant 2.1.2 → 2.2.0

package/templates/skills/assess/SKILL.md

@@ -115,6 +115,7 @@ Surface red flags. Only track signals that change the recommendation.
 | security, auth, authentication, permissions | Domain | `spec → security-review → exec → qa` |
 | ui, frontend, admin, web, browser | Domain | `spec → exec → test → qa` |
 | complex, refactor, breaking, major | Modifier | `spec → exec → qa` + `-q` |
+| (ui/frontend) + (enhancement/feature), or testable-AC signals | Modifier | inserts `testgen` before `exec` (see Testgen detection below) |
 | enhancement, feature (default) | Generic | `spec → exec → qa` |
 | bug, fix, hotfix, patch | Generic | `exec → qa` |
 | docs, documentation, readme | Generic | `exec → qa` |
@@ -131,10 +132,24 @@ Surface red flags. Only track signals that change the recommendation.
 
 **Quality loop (`-q`):** Recommend for everything except simple bug fixes and docs-only.
 
-**Other flags:**
-- `--chain` — Chain issues: each branches from previous (implies --sequential)
-- `--qa-gate` — Pause chain on QA failure, preventing downstream issues from building on broken code (requires --chain)
-- `--base <branch>` — Issue references a feature branch
+**Testgen detection:** Add `testgen` to the workflow when any apply:
+- Labels include (`ui` or `frontend`) AND (`enhancement` or `feature`)
+- ACs reference "unit test", "integration test", or list "Automated Test" as a verification method
+
+Skip when: only `bug`/`fix` labels present, only `docs` label present, or a prior `testgen` phase marker exists in issue comments.
+
+**Chain detection (suggest-only, never auto-apply):** When 2+ assessed issues have a detected dependency, emit a `Chain:` line alongside (not replacing) the default per-issue commands. False dependency inference produces silently-wrong branch topology, so the user decides.
+
+Triggers (any one):
+- Issue body or comments mention `"depends on #N"`, `"blocked by #N"`, or `"after #N"`
+- One issue's described output is another issue's input (e.g., A changes a function signature that B consumes)
+
+Format: `Chain: npx sequant run <N1> <N2> --chain --qa-gate -q <phases>   # alternative — <one-line reason>`
+
+Flag references:
+- `--chain` chains issues (each branches from previous; implies `--sequential`)
+- `--qa-gate` pauses chain on QA failure (requires `--chain`)
+- `--base <branch>` — issue references a feature branch
 
 ### Step 5: Conflict Detection
 
@@ -155,20 +170,25 @@ For each active worktree, check `git diff --name-only main...HEAD` for file over
 **Table column rules:** The "Reason" column must not be truncated mid-word. If a row's reason text would exceed the column width, prefer abbreviating the reason to a shorter synonym rather than cutting a word in half. Column widths should adapt to content — do not force a fixed table width.
 
 ```
- #    Action     Reason                              Run
-<N>   <ACTION>   <short reason>                       <workflow or symbol>
-<N>   <ACTION>   <short reason>                       <workflow or symbol>
+ #    Action     [ACs]  Reason                              Run
+<N>   <ACTION>   [N]    <short reason>                       <workflow or symbol>
+<N>   <ACTION>   [N]    <short reason>                       <workflow or symbol>
 ...
 ────────────────────────────────────────────────────────────────
-
-    npx sequant run <N1> <N2> <flags>
-    npx sequant run <N3> <flags>              # resume
-
+Commands:
+  npx sequant run <N1> <N2> <flags>
+  npx sequant run <N3> <flags>              # resume
 ────────────────────────────────────────────────────────────────
-Order: <N> → <N> (<shared file>) · <N> → <N> (<dependency>)
+Order: <N> → <N> (<dependency reason>)
 
 ⚠ #<N>  <warning>
 ⚠ #<N>  <warning>
+
+Chain: npx sequant run <N1> <N2> --chain --qa-gate -q <phases>   # alternative — <reason>
+
+Flags:
+  <flag>                <one-line reason>
+  <flag>                <one-line reason>
 ────────────────────────────────────────────────────────────────
 Cleanup:
   <executable command>                 # reason
@@ -181,6 +201,8 @@ Cleanup:
 <!-- assess:quality-loop=<bool> -->
 ```
 
+**`ACs` column (conditional):** Include the `ACs` column only when every assessed issue has at least one explicit `- [ ]` checkbox AC in its body. Otherwise omit the column entirely — do not show partial values. The counter prevents eroding table trust when some issues use implicit/narrative ACs.
+
 #### Run Column Symbols
 
 | Symbol | Meaning | Example |
@@ -195,26 +217,51 @@ Cleanup:
 | `‖` | Blocked/deferred | Dependency or manual |
 | `—` | No action needed | Already closed/merged |
 
-#### Command Block Rules
+#### Commands Block Rules
+
+The commands block is headed by `Commands:` — no box-drawing, no character counting. The header label is the visual anchor.
 
 1. Only PROCEED and REWRITE issues get commands
 2. Group by identical phases + flags → same line
 3. Resume issues get `# resume` comment
 4. Rewrite issues get `# restart` comment
-5. Chain mode issues use `--chain` flag
+5. Chain mode issues use `--chain` flag (see `Chain:` annotation rules below)
 6. If ALL issues share the same workflow, emit a single command
 7. **Line splitting:** When a single command would contain more than 6 issue numbers, split into multiple commands of at most 6 issues each, grouped by compatible workflow. Example: 11 issues → two commands (6 + 5)
 
 #### Annotation Rules
 
-- **`Order:`** — Only when sequencing matters (shared files or dependencies). Format: `A → B (reason)` joined by ` · `
-- **`⚠` warnings** — Only non-obvious signals (complexity, staleness, dual concerns). One line each. Prefix with issue number.
+Emit annotations in this order between the separators that follow `Commands:`:
+`Order:` → `⚠` warnings → `Chain:` → `Flags:`. `Cleanup:` goes in its own block after. Omit any section (and its surrounding blank line) when it has no content.
+
+- **`Order:`** — Only when sequencing matters. Include the **reason** for the ordering, not just `(<filename>)`. Prefer dependency reasoning over filename.
+  - Good: `Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)`
+  - Good: `Order: 460 → 461 (460 adds batch-executor tests that 461's label matching depends on)`
+  - Avoid bare filenames when a reason is clearer.
+
+- **`⚠` warnings** — Only non-obvious signals (complexity, staleness, dual concerns, partial-AC satisfaction). One line each, prefixed with issue number. Warnings can note when part of an AC is already satisfied in the codebase:
+  - `⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected`
+  - `⚠ #412  bug + auth labels — domain label (auth) takes priority over bug`
+
+- **`Chain:`** — Only when 2+ PROCEED issues have a detected dependency (see "Chain detection" in Step 4). Suggests an alternative execution topology. Does not replace the default per-issue commands. Format:
+  `Chain: npx sequant run <N1> <N2> --chain --qa-gate -q <phases>   # alternative — <one-line reason>`
+
+- **`Flags:`** — Only when non-default flags appear in the commands and the reason isn't obvious. One line per **distinct** flag used across all commands. Omit entire section when `-q` is the only non-default flag AND its reason is obvious (e.g., all issues are enhancements). Format:
+  ```
+  Flags:
+    -q                   9+ ACs or multi-file scope
+    --testgen            testable ACs detected (UI hooks + API integration)
+    --phases ...,test    ui label → browser verification
+  ```
+
 - **`Cleanup:`** — Only when actionable (stale branches, merged-but-open issues, label changes). Show as executable commands with `# reason` comments.
-- **Omit entire section** (including its separator) when no annotations of that type exist.
+
 - **"All clear" is silence** — no annotation means no issues.
 
 #### Batch Example (mixed states, with label priority)
 
+Not all issues have explicit `- [ ]` checkboxes, so the `ACs` column is omitted.
+
 ```
  #    Action     Reason                              Run
  462  PARK       Manual measurement task              ‖
@@ -227,19 +274,22 @@ Cleanup:
  411  PROCEED    Config path normalization              ◂ exec → qa
  405  REWRITE    PR #380 200+ commits behind           ⟳ spec → exec → qa
 ────────────────────────────────────────────────────────────────
-
-    npx sequant run 461 460 -q --phases exec,qa
-    npx sequant run 458 443 -q
-    npx sequant run 412 -q --phases spec,security-review,exec,qa
-    npx sequant run 411 -q --phases exec,qa     # resume
-    npx sequant run 405 -q                      # restart
-
+Commands:
+  npx sequant run 461 460 -q --phases exec,qa
+  npx sequant run 458 443 -q
+  npx sequant run 412 -q --phases spec,security-review,exec,qa
+  npx sequant run 411 -q --phases exec,qa     # resume
+  npx sequant run 405 -q                      # restart
 ────────────────────────────────────────────────────────────────
-Order: 460 → 461 (batch-executor.ts)
+Order: 460 → 461 (460 adds batch-executor tests that 461's label matching depends on)
 
 ⚠ #458  Dual concern (UX + race) across 4 files
 ⚠ #405  Stale 30+ days, ACs still valid
 ⚠ #412  bug + auth labels — domain label (auth) takes priority over bug
+
+Flags:
+  -q                   multi-file scope across most PROCEED issues
+  --phases spec,...    spec phase added for 458/443/412/405 (standard features)
 ────────────────────────────────────────────────────────────────
 Cleanup:
   git worktree remove .../447-...      # merged, stale worktree
@@ -258,9 +308,39 @@ Cleanup:
 <!-- #405 assess:action=REWRITE assess:phases=spec,exec,qa assess:quality-loop=true -->
 ```
 
+#### Batch Example (dependent issues with testgen, chain suggestion)
+
+All issues have explicit checkbox ACs, so the `ACs` column is shown. A dependency is detected (185 → 186), so a `Chain:` suggestion appears alongside the default commands.
+
+```
+ #    Action    ACs  Reason                           Run
+ 185  PROCEED    6   Domain error standardization      spec → exec → qa
+ 186  PROCEED    9   React Query hooks migration       spec → testgen → exec → test → qa
+────────────────────────────────────────────────────────────────
+Commands:
+  npx sequant run 185 -q
+  npx sequant run 186 -q --phases spec,testgen,exec,test,qa
+────────────────────────────────────────────────────────────────
+Order: 185 → 186 (185 changes fetchApi error format that 186 consumes)
+
+⚠ #185  Domain errors already exist in repository layer — scope may be smaller than expected
+⚠ #186  @tanstack/react-query not installed; large scope (9 hooks + optimistic updates)
+
+Chain: npx sequant run 185 186 --chain --qa-gate -q --phases spec,testgen,exec,test,qa
+       # alternative — use if 186 should branch from 185's work
+
+Flags:
+  --testgen             #186 has testable ACs (UI hooks + API integration)
+  --phases ...,test     #186 ui label → browser verification
+────────────────────────────────────────────────────────────────
+
+<!-- #185 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
+<!-- #186 assess:action=PROCEED assess:phases=spec,testgen,exec,test,qa assess:quality-loop=true -->
+```
+
 #### Batch Example (all clean)
 
-When every issue is PROCEED with no warnings, the output is minimal:
+When every issue is PROCEED with no warnings, no dependencies, and no non-default flags beyond an obvious `-q`, the output is minimal. The `Flags:` section is omitted because `-q` is obvious here (all PROCEED enhancements).
 
 ```
  #    Action     Reason                              Run
@@ -268,10 +348,9 @@ When every issue is PROCEED with no warnings, the output is minimal:
  460  PROCEED    batch-executor tests                  exec → qa
  443  PROCEED    Consolidate gh calls                  spec → exec → qa
 ────────────────────────────────────────────────────────────────
-
-    npx sequant run 461 460 -q --phases exec,qa
-    npx sequant run 443 -q
-
+Commands:
+  npx sequant run 461 460 -q --phases exec,qa
+  npx sequant run 443 -q
 ────────────────────────────────────────────────────────────────
 
 <!-- #461 assess:action=PROCEED assess:phases=exec,qa assess:quality-loop=true -->
@@ -279,9 +358,11 @@ When every issue is PROCEED with no warnings, the output is minimal:
 <!-- #443 assess:action=PROCEED assess:phases=spec,exec,qa assess:quality-loop=true -->
 ```
 
+Silence means clean — no `Order:`, no `⚠`, no `Chain:`, no `Flags:`, no `Cleanup:`.
+
 #### Batch Example (large batch, 13 issues with Rule 7 split)
 
-When assessing 9+ issues, commands are split per Rule 7 (max 6 issue numbers per line), and the table adapts to content width:
+When assessing 9+ issues, commands are split per Rule 7 (max 6 issue numbers per line), and the table adapts to content width. Mixed AC styles across issues → `ACs` column omitted.
 
 ```
  #    Action     Reason                                   Run
@@ -299,18 +380,21 @@ When assessing 9+ issues, commands are split per Rule 7 (max 6 issue numbers per
  492  PROCEED    Add export command                         spec → exec → qa
  491  PROCEED    Normalize config paths                     exec → qa
 ────────────────────────────────────────────────────────────────
-
-    npx sequant run 503 502 501 498 495 494 -q --phases exec,qa
-    npx sequant run 491 -q --phases exec,qa
-    npx sequant run 499 -q --phases spec,exec,test,qa
-    npx sequant run 500 -q --phases spec,security-review,exec,qa
-    npx sequant run 497 492 -q
-
+Commands:
+  npx sequant run 503 502 501 498 495 494 -q --phases exec,qa
+  npx sequant run 491 -q --phases exec,qa
+  npx sequant run 499 -q --phases spec,exec,test,qa
+  npx sequant run 500 -q --phases spec,security-review,exec,qa
+  npx sequant run 497 492 -q
 ────────────────────────────────────────────────────────────────
-Order: 497 → 492 (batch-executor.ts)
+Order: 497 → 492 (497 refactors batch-executor internals that 492's export command uses)
 
 ⚠ #500  bug + auth labels — domain label takes priority
 ⚠ #499  bug + ui labels — domain label triggers test phase
+
+Flags:
+  --phases ...,security-review   #500 auth label → security review required
+  --phases ...,test              #499 ui label → browser verification
 ────────────────────────────────────────────────────────────────
 Cleanup:
   gh issue close 493                   # duplicate of #491
@@ -346,9 +430,13 @@ More context since you're focused on one issue. Separators between every section
 
 → PROCEED — <one-line reason>
 
-    npx sequant run <N> <flags>
+Commands:
+  npx sequant run <N> <flags>
+
+<phases> · <N> ACs
 
-<phases> · <N> ACs · <flag reasoning>
+Flags:
+  <flag>        <one-line reason>
 ────────────────────────────────────────────────────────────────
 ⚠ <warning if any>
 ⚠ Conflict: #<N> also modifies <path>
@@ -359,7 +447,9 @@ More context since you're focused on one issue. Separators between every section
 <!-- assess:quality-loop=<bool> -->
 ```
 
-If no warnings exist, omit the warning section and its separator:
+**`Flags:` (single mode):** Indented list of each enabled non-default flag with a one-line reason. Omit the entire `Flags:` section when `-q` is the only non-default flag AND the reason is obvious (e.g., a straightforward enhancement). Do not repeat obvious flags.
+
+Example with `Flags:` (non-obvious `-q` + `--testgen`):
 
 ```
 #458 — Parallel run UX freeze + reconcileState race condition
@@ -368,9 +458,33 @@ Open · bug, enhancement, cli
 
 → PROCEED — Both root causes confirmed in codebase
 
-    npx sequant run 458 -q
+Commands:
+  npx sequant run 458 -q
+
+spec → exec → qa · 8 ACs
+
+Flags:
+  -q     dual concern across 4 files
+────────────────────────────────────────────────────────────────
+
+<!-- assess:action=PROCEED -->
+<!-- assess:phases=spec,exec,qa -->
+<!-- assess:quality-loop=true -->
+```
+
+Example omitting `Flags:` (obvious `-q` for a standard enhancement):
+
+```
+#443 — Consolidate gh CLI calls
+Open · enhancement
+────────────────────────────────────────────────────────────────
 
-spec → exec → qa · 8 ACs · -q (dual concern)
+→ PROCEED — Codebase matches spec, 5 ACs
+
+Commands:
+  npx sequant run 443 -q
+
+spec → exec → qa · 5 ACs
 ────────────────────────────────────────────────────────────────
 
 <!-- assess:action=PROCEED -->
@@ -448,7 +562,8 @@ Need: <specific information required>
 
 → REWRITE — <reason>
 
-    npx sequant run <N> <flags>                 # fresh start
+Commands:
+  npx sequant run <N> <flags>                 # fresh start
 
 <phases> · <N> ACs
 ────────────────────────────────────────────────────────────────
@@ -466,27 +581,19 @@ Need: <specific information required>
 
 | Section | Show when |
 |---------|-----------|
-| Command block | At least one PROCEED or REWRITE issue |
+| `ACs` column (batch) | Every assessed issue has ≥1 explicit `- [ ]` checkbox AC |
+| `Commands:` block | At least one PROCEED or REWRITE issue |
 | `Order:` | File conflicts or dependencies require sequencing |
-| `⚠` warnings | Non-obvious signals exist |
+| `⚠` warnings | Non-obvious signals exist (complexity, staleness, dual concerns, partial-AC satisfaction) |
+| `Chain:` | 2+ PROCEED issues with detected dependency (suggest-only) |
+| `Flags:` | Non-default flags appear AND `-q` is not the sole flag with an obvious reason |
 | `Cleanup:` | Stale branches, merged-but-open issues, or label changes |
 | Separators | Between sections that are both shown; omit if adjacent section is omitted |
 
-Every separator and section is conditional. If there are no warnings and no cleanup, the output is just: table → separator → command block → separator → markers.
+Every separator and section is conditional. If there are no warnings, no chain, no flags, and no cleanup, the output is just: table → separator → `Commands:` block → separator → markers.
 
 ---
 
-## State Tracking
-
-Initialize state for each assessed issue:
-
-```bash
-TITLE=$(gh issue view <N> --json title -q '.title')
-npx tsx scripts/state/update.ts init <N> "$TITLE"
-```
-
-Note: `/assess` only initializes issues — actual phase tracking happens during workflow execution.
-
 ## Persist Analysis
 
 After displaying output, prompt the user to save using `AskUserQuestion` with options "Yes (Recommended)" and "No".
@@ -516,10 +623,16 @@ If confirmed, post a structured comment to each issue via `gh issue comment`. Ea
 
 - [ ] Every issue has exactly one action in the table
 - [ ] Run column uses correct symbol for the action/state
-- [ ] Command block only contains PROCEED and REWRITE issues
-- [ ] Commands are grouped by compatible workflow
-- [ ] Separators appear between every shown section
-- [ ] Annotations omitted when not applicable (silence = healthy)
+- [ ] `ACs` column included only when every issue has explicit `- [ ]` checkboxes
+- [ ] Commands appear under a `Commands:` header (no bare indented block, no box-drawing)
+- [ ] Commands block only contains PROCEED and REWRITE issues, grouped by compatible workflow
+- [ ] `testgen` included when ui/frontend + enhancement/feature labels OR testable-AC signals
+- [ ] `Chain:` suggested (not auto-applied) when 2+ PROCEED issues have a detected dependency
+- [ ] `Flags:` section present when non-default flags appear (unless only obvious `-q`)
+- [ ] `Order:` annotations carry dependency **reasoning**, not bare filenames
+- [ ] `⚠` warnings include partial-AC satisfaction where applicable
+- [ ] Separators appear between every shown section; omitted when adjacent section is omitted
+- [ ] Annotations/sections omitted when not applicable (silence = healthy)
 - [ ] HTML markers present for every assessed issue
 - [ ] Batch mode: table is the primary output, no per-issue detail sections
 - [ ] Single mode: focused summary with separators between sections

package/templates/skills/exec/SKILL.md

@@ -806,16 +806,6 @@ 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:
@@ -1924,37 +1914,6 @@ 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:**

package/templates/skills/fullsolve/SKILL.md

@@ -854,33 +854,7 @@ As an orchestrator, `/fullsolve` must:
    export SEQUANT_WORKTREE=<worktree-path>
    ```
 
-2. **Initialize issue state at workflow start:**
-   ```bash
-   npx tsx scripts/state/update.ts init <issue-number> "<issue-title>"
-   ```
-
-3. **Update phase status** at each transition:
-   ```bash
-   # Before invoking child skill
-   npx tsx scripts/state/update.ts start <issue-number> <phase>
-
-   # After child skill completes
-   npx tsx scripts/state/update.ts complete <issue-number> <phase>
-
-   # If child skill fails
-   npx tsx scripts/state/update.ts fail <issue-number> <phase> "Error"
-   ```
-
-4. **Update final status** after workflow completes:
-   ```bash
-   # On READY_FOR_MERGE
-   npx tsx scripts/state/update.ts status <issue-number> ready_for_merge
-
-   # On failure
-   npx tsx scripts/state/update.ts status <issue-number> blocked
-   ```
-
-**Why child skills skip state updates:** When `SEQUANT_ORCHESTRATOR` is set, child skills defer state management to the orchestrator to avoid duplicate updates.
+2. **State tracking** is handled automatically by the orchestrator runtime when `SEQUANT_ORCHESTRATOR` is set. Child skills defer state management to the orchestrator to avoid duplicate updates.
 
 ---
 

package/templates/skills/qa/SKILL.md

@@ -122,10 +122,23 @@ Include this marker in every `gh issue comment` that represents QA completion.
 Invocation:
 
 - `/qa 123`: Treat `123` as the GitHub issue/PR identifier in context.
+- `/qa 123 172`: Treat both as issue numbers — process each sequentially.
 - `/qa <freeform description>`: Treat the text as context about the change to review.
 - `/qa 123 --parallel`: Force parallel agent execution (faster, higher token usage).
 - `/qa 123 --sequential`: Force sequential agent execution (slower, lower token usage).
 
+### Multi-Issue Invocation
+
+When multiple issue numbers are provided (e.g., `/qa 167 172`):
+
+1. **Parse all issue numbers** from args
+2. **Process each issue sequentially** with inline code review — do NOT spawn ad-hoc background agents for the diff reading or AC verification portions
+3. The built-in `sequant-qa-checker` sub-agents (type safety, scope, security) continue to run per the size gate rules for each issue
+4. Each issue gets its own full QA cycle: context fetch → diff review → quality checks → verdict → comment
+5. Post a **separate QA comment** to each issue's GitHub thread
+
+**Why sequential with inline review:** Ad-hoc background agents for code review are unreliable — they hallucinate about file existence, misattribute API patterns, and hit permission issues on worktree reads. The narrowly-scoped `sequant-qa-checker` agents work well because they have specific, bounded tasks. The code review portion must stay inline for accuracy.
+
 ### Agent Execution Mode
 
 Before spawning quality check agents, determine the execution mode:
@@ -838,6 +851,12 @@ issue_type="${SEQUANT_ISSUE_TYPE:-}"
 admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1 || true)
 ```
 
+**Add skill sync check if skill files modified:**
+```bash
+skill_modified=$(git diff main...HEAD --name-only | grep -E "^\.(claude/skills|skills|templates/skills)/" | head -1 || true)
+```
+If skill files are modified, the quality-checks.sh script automatically runs the three-directory sync check (section 12). If divergence is detected, this blocks `READY_FOR_MERGE` — verdict becomes `AC_MET_BUT_NOT_A_PLUS` with a note to run `npx tsx scripts/check-skill-sync.ts --fix`.
+
 See [quality-gates.md](references/quality-gates.md) for detailed verdict synthesis.
 
 ### Using MCP Tools (Optional)

package/templates/skills/qa/scripts/quality-checks.sh

@@ -385,7 +385,53 @@ else
 fi
 
 # =============================================================================
-# 11. Build Verification (cacheable - expensive operation)
+# =============================================================================
+# 11.5. Skill Sync Check (when skill files modified)
+# =============================================================================
+echo ""
+skill_files_changed=$(git diff main...HEAD --name-only | grep -E '^\.(claude/skills|skills|templates/skills)/' || true)
+if [[ -n "$skill_files_changed" ]]; then
+  echo "🔍 Checking three-directory skill sync..."
+  if [[ -f "scripts/check-skill-sync.ts" ]]; then
+    sync_output=$(npx tsx scripts/check-skill-sync.ts 2>&1 || true)
+    sync_exit=$?
+    sync_summary=$(echo "$sync_output" | grep "^Summary:" || true)
+    if [[ $sync_exit -ne 0 ]]; then
+      echo "⚠️  Skill sync: DIVERGENCE DETECTED"
+      echo "$sync_summary"
+      echo "   Run: npx tsx scripts/check-skill-sync.ts --fix"
+    else
+      echo "✅ Skill sync: All files synced across 3 directories"
+    fi
+  else
+    echo "   (scripts/check-skill-sync.ts not found — using inline diff)"
+    diverged=0
+    for f in $skill_files_changed; do
+      if [[ "$f" == .claude/skills/* ]]; then
+        rel="${f#.claude/skills/}"
+        for mirror in "templates/skills" "skills"; do
+          if [[ -f "${mirror}/${rel}" ]]; then
+            if ! diff -q ".claude/skills/${rel}" "${mirror}/${rel}" > /dev/null 2>&1; then
+              echo "   ⚠️  DIVERGED: ${rel} (.claude/skills vs ${mirror})"
+              diverged=$((diverged + 1))
+            fi
+          fi
+        done
+      fi
+    done
+    if [[ $diverged -eq 0 ]]; then
+      echo "✅ Skill sync: Changed skill files are synced"
+    else
+      echo "⚠️  Skill sync: ${diverged} file(s) diverged"
+      echo "   Fix: copy from .claude/skills/ to templates/skills/ and skills/"
+    fi
+  fi
+else
+  echo "🔍 Skill sync: No skill files changed (skipped)"
+fi
+
+# =============================================================================
+# 12. Build Verification (cacheable - expensive operation)
 # =============================================================================
 
 verify_build_against_main() {