@ngocsangairvds/vsaf 5.1.5 → 5.1.6

package/skills/sdlc/hotfix/review/gate/step.md

@@ -0,0 +1,51 @@
+## Gate
+
+Write `## Gate: APPROVED` or `## Gate: CHANGES_REQUESTED` with reasons.
+
+If CHANGES_REQUESTED:
+- List specific issues with triage: MUST FIX / SHOULD FIX / NOTED
+- Do NOT proceed to ship until all MUST FIX items are resolved
+
+## Output
+
+Write file: `.vsaf/docs/hotfixes/{bug-id}/02-review.md`
+
+```markdown
+# Hotfix Review: {bug-id}
+
+## Minimality Check
+{minimality check results}
+
+## Test Quality Check
+{test quality check results}
+
+## Blast Radius
+{blast radius confirmation — matches/exceeds analysis}
+
+## SonarQube
+{quality gate results on changed files}
+
+## Conclusion
+{overall assessment}
+
+## Gate: {APPROVED / CHANGES_REQUESTED}
+{reasons if changes requested}
+```
+
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+- Bug: {bug-id}
+- Status: REVIEW COMPLETED
+- Gate: {APPROVED / CHANGES_REQUESTED}
+- Output: `.vsaf/docs/hotfixes/{bug-id}/02-review.md`
+- Next step: `/sdlc-ship` (if approved)
+
+Update `.vsaf/docs/STATUS.md`.
+
+## Rules
+
+- ⛔ Do NOT modify code — review only
+- ⛔ Do NOT modify `graphify-out/` or `.gitnexus/`
+- A hotfix review is FAST but NOT sloppy — every check matters
+- If the fix touches more files than the analysis predicted, escalate to human

package/skills/sdlc/hotfix/review/impact/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-review-impact
+description: "Hotfix Review 4/4 — impact and quality gate"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Review 4/4 — impact and quality gate
+
+@include(step.md)

package/skills/sdlc/hotfix/review/impact/step.md

@@ -0,0 +1,22 @@
+### Step 4: Impact Check + SonarQube
+
+```
+[HOTFIX-REVIEW] [4/4] Impact check + quality gate... ⏳
+```
+
+1. Use GitNexus `detect_changes` + `impact` — confirm blast radius matches the analysis
+2. If blast radius is LARGER than analysis predicted → flag for human review
+3. SonarQube rules on changed files only:
+
+| Metric | Threshold |
+|--------|-----------|
+| Issues (Blocker) | 0 |
+| Issues (Critical) | 0 |
+| Security Hotspots | 0 |
+| New code smells | 0 |
+
+> **Standard (single source of truth):** **`.claude/skills/_shared/sdlc/sonar-viettel/quality-gate.md`** — full gate + 357-rule parameters + importable `sonar-viettel-profile.xml` / `sonar-viettel-gate.json`. Same file Phase 3 (`/sdlc-hotfix-implement`) coded against. If SonarQube is present, scan changed files against the `sonar-viettel` profile + gate; otherwise re-check manually. `New code smells = 0` is intentionally stricter than the gate's ≤20 for surgical fixes.
+
+```
+[HOTFIX-REVIEW] [4/4] Impact check + quality gate... ✅
+```

package/skills/sdlc/hotfix/review/minimality/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-review-minimality
+description: "Hotfix Review 2/4 — minimality verification"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Review 2/4 — minimality verification
+
+@include(step.md)

package/skills/sdlc/hotfix/review/minimality/step.md

@@ -0,0 +1,18 @@
+### Step 2: Minimality Verification
+
+```
+[HOTFIX-REVIEW] [2/4] Verifying fix is minimal... ⏳
+```
+
+Check:
+- [ ] Only files identified in the analysis were changed
+- [ ] No unnecessary refactoring included
+- [ ] No formatting-only changes on untouched code
+- [ ] No unrelated fixes bundled in
+- [ ] Diff size is proportional to the bug (a 1-line bug should not need 50 lines of changes)
+
+If any check fails → flag as CHANGES_REQUESTED with specific reason.
+
+```
+[HOTFIX-REVIEW] [2/4] Verifying fix is minimal... ✅
+```

package/skills/sdlc/hotfix/review/test-quality/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-review-test-quality
+description: "Hotfix Review 3/4 — test quality check"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Review 3/4 — test quality check
+
+@include(step.md)

package/skills/sdlc/hotfix/review/test-quality/step.md

@@ -0,0 +1,16 @@
+### Step 3: Test Quality Check
+
+```
+[HOTFIX-REVIEW] [3/4] Verifying test quality... ⏳
+```
+
+Read the reproduction test and verify:
+- [ ] Test targets the specific bug (not a generic happy-path test)
+- [ ] Test would FAIL without the fix (it's not trivially always-passing)
+- [ ] Test exercises the exact code path from the root cause analysis
+- [ ] Test has a descriptive name referencing the bug
+- [ ] Test follows project conventions
+
+```
+[HOTFIX-REVIEW] [3/4] Verifying test quality... ✅
+```

package/skills/sdlc/hotfix/ship/commit-pr/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-commit-pr
+description: "Hotfix Ship 4/5 — commit push PR"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 4/5 — commit push PR
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/commit-pr/step.md

@@ -0,0 +1,58 @@
+### Step 4: Commit + Push + PR
+
+```
+[HOTFIX-SHIP] [4/5] Commit + push + create PR... ⏳
+```
+
+**Commit scope — ONLY commit:**
+- Source code changes (the fix)
+- `.vsaf/docs/hotfixes/{bug-id}/` (all artifacts)
+- `.gitignore` (if updated)
+
+**DO NOT commit:**
+- `graphify-out/`
+- `.gitnexus/`
+
+**Commit message format:**
+```
+fix({area}): {short description}
+
+Root cause: {one line from 01-analysis.md}
+Closes: #{issue-number} (if applicable)
+```
+
+**Push + PR:**
+```bash
+git push -u origin hotfix/{bug-id}
+gh pr create --title "fix({area}): {short description}" --body "{PR body}"
+```
+
+**PR body template:**
+```markdown
+## Bug Fix: {bug-id}
+
+### Root Cause
+{from 01-analysis.md — one paragraph}
+
+### Fix
+{from 03-impl-log.md — what was changed and why}
+
+### Tests
+- Regression test: `{test file}:{test name}`
+- Full suite: {total} tests, all PASS
+
+### Affected Files
+{list from 03-impl-log.md}
+
+### Scope
+- ✅ Fix only — no refactoring, no enhancements
+- ✅ Regression test added
+- ✅ Full test suite passing
+
+---
+> **Post-pull:** Run `npx gitnexus analyze` and `/graphify` to re-index locally.
+```
+
+```
+[HOTFIX-SHIP] [4/5] Commit + push + create PR... ✅
+```

package/skills/sdlc/hotfix/ship/entry/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-entry
+description: "Hotfix Ship 1/5 — check prerequisites"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 1/5 — check prerequisites
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/entry/step.md

@@ -0,0 +1,20 @@
+## Phase Entry Protocol
+
+```
+[HOTFIX-SHIP] [1/5] Checking prerequisites... ⏳
+```
+
+1. Input: `.vsaf/docs/hotfixes/{bug-id}/` directory
+2. Verify these files exist:
+   - `01-analysis.md` — root cause analysis
+   - `02-prd.md` — fix requirements (MUST have `## Gate: APPROVED`)
+   - `03-impl-log.md` — implementation log
+3. Check `02-prd.md` has `## Gate: APPROVED`
+   - No Gate → Stop: "PRD not approved. Get approval before shipping."
+4. Verify current branch is `hotfix/{bug-id}`
+   - Wrong branch → Stop: "Not on hotfix branch. Switch to `hotfix/{bug-id}`."
+5. Read `CONTEXT.md`
+
+```
+[HOTFIX-SHIP] [1/5] Checking prerequisites... ✅
+```

package/skills/sdlc/hotfix/ship/exit/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-exit
+description: "Hotfix Ship — exit protocol and rules"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship — exit protocol and rules
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/exit/step.md

@@ -0,0 +1,31 @@
+## Phase Exit Protocol
+
+Print PHASE REPORT:
+```
+═══════════════════════════════════════════
+  HOTFIX SHIPPED: {bug-id}
+═══════════════════════════════════════════
+  Flow: Analyze → PRD → Implement → Ship
+  
+  PR: #{number} — {url}
+  Branch: hotfix/{bug-id}
+  Commit: source code + .vsaf/docs/ only
+  Excluded: graphify-out/, .gitnexus/
+  
+  Artifacts: .vsaf/docs/hotfixes/{bug-id}/ (4 files)
+  
+  Hotfix DONE.
+═══════════════════════════════════════════
+```
+
+Update `.vsaf/docs/STATUS.md` → move to "Completed Hotfixes".
+
+## Rules
+
+- ⛔ Do NOT review code — that happened during TDD (self-review via SonarQube)
+- ⛔ Do NOT commit `graphify-out/` or `.gitnexus/`
+- ⛔ Do NOT ship if tests are failing
+- ⛔ Do NOT ship without PRD Gate: APPROVED
+- Gate comes from PRD approval — no separate review phase needed
+- PR description MUST be self-contained
+- Commit message follows conventional format: `fix({area}): {description}`

package/skills/sdlc/hotfix/ship/gitignore/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-gitignore
+description: "Hotfix Ship 2/5 — .gitignore enforcement"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 2/5 — .gitignore enforcement
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/gitignore/step.md

@@ -0,0 +1,22 @@
+### Step 2: .gitignore Enforcement
+
+```
+[HOTFIX-SHIP] [2/5] Checking .gitignore... ⏳
+```
+
+**MANDATORY** — verify before committing:
+
+1. Check `.gitignore` contains:
+   ```
+   graphify-out/
+   .gitnexus/
+   ```
+2. If MISSING → add automatically and notify user
+3. Verify with `git status` — `graphify-out/` and `.gitnexus/` do NOT appear
+4. If they appear → `git rm --cached -r graphify-out/ .gitnexus/`
+
+⚠️ **ABSOLUTELY DO NOT commit `graphify-out/` or `.gitnexus/`**
+
+```
+[HOTFIX-SHIP] [2/5] Checking .gitignore... ✅
+```

package/skills/sdlc/hotfix/ship/report/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-report
+description: "Hotfix Ship 5/5 — ship report"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 5/5 — ship report
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/report/step.md

@@ -0,0 +1,47 @@
+### Step 5: Ship Report
+
+```
+[HOTFIX-SHIP] [5/5] Writing ship report... ⏳
+```
+
+Write file: `.vsaf/docs/hotfixes/{bug-id}/04-ship.md`
+
+```markdown
+# Ship Report: {bug-id}
+
+## PR
+- {repo}: PR #{number} — {url}
+
+## Branch
+`hotfix/{bug-id}` → `main`
+
+## Commit Scope
+- Source code: {N} files (minimal fix)
+- .vsaf/docs/: {M} files (hotfix artifacts)
+- Excluded: graphify-out/, .gitnexus/ (local index)
+
+## Final Status
+- Build: PASS
+- Tests: all GREEN (including regression test)
+- PRD Gate: APPROVED
+
+## Bug Fix Summary
+- Root cause: {from 01-analysis.md}
+- Regression test: {test file}:{test name}
+- Fix: {minimal diff description}
+
+## Artifacts
+- `01-analysis.md` — root cause analysis
+- `02-prd.md` — fix requirements (approved)
+- `03-impl-log.md` — TDD implementation log
+- `04-ship.md` — this file
+
+## Post-pull Setup
+After pulling the code, run:
+- `npx gitnexus analyze` — re-index code
+- `/graphify` — rebuild knowledge graph
+```
+
+```
+[HOTFIX-SHIP] [5/5] Writing ship report... ✅
+```

package/skills/sdlc/hotfix/ship/test-gate/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-hotfix-ship-test-gate
+description: "Hotfix Ship 3/5 — final test gate"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Hotfix Ship 3/5 — final test gate
+
+@include(step.md)

package/skills/sdlc/hotfix/ship/test-gate/step.md

@@ -0,0 +1,17 @@
+### Step 3: Final Test Gate
+
+```
+[HOTFIX-SHIP] [3/5] Final test verification... ⏳
+```
+
+Run full test suite one last time before shipping:
+```bash
+npm test  # or mvn test / gradle test / equivalent
+```
+
+- ALL tests MUST pass
+- If FAIL → Stop: "Tests failing. Fix before shipping."
+
+```
+[HOTFIX-SHIP] [3/5] Final test verification... ✅
+```

package/skills/sdlc/implement/build-run/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-build-run
+description: "Implement 7/8 — build + run verification"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 7/8 — build + run verification
+
+@include(step.md)

package/skills/sdlc/implement/build-run/step.md

@@ -0,0 +1,85 @@
+### Step 7: Build & Run Verification
+
+```
+[IMPLEMENT] [7/8] Build & run verification... ⏳
+```
+
+**MANDATORY** — code MUST compile and run successfully before exiting the phase.
+
+1. **Compile check**: Build the entire project → MUST have 0 errors
+   - Java: `mvn compile` or `gradle build`
+   - Node: `npm run build` / `tsc --noEmit`
+   - Angular: `ng build`
+   - Go: `go build ./...`
+   - If FAIL → fix immediately, DO NOT skip
+
+2. **Run verification**: Start application → MUST start successfully
+   - If the project has `docker-compose.yml` → `docker compose up`
+   - If not → use native run command
+   - Check health endpoint / startup log OK
+
+3. **Environment check**:
+   - Detect required runtime (JDK, Node, Python, Go, etc.)
+   - If runtime missing → ⚠️ **WARNING**: "Missing {runtime}. Cannot verify build."
+   - **Recommend Docker**: "Recommend using Docker to ensure a consistent environment. Create a Dockerfile if one does not exist."
+   - If Docker available → prefer building in container
+
+4. **Test suite run**: `npm test` / `mvn test` / equivalent → All tests PASS
+
+5. **Final SonarQube sweep**: Scan all new code one last time before exiting
+   - Confirm both New Code and Overall Code conditions are green per the shared `quality-gate.md` (single source of truth)
+   - If FAIL → fix immediately, this is a hard gate
+
+⚠️ **DO NOT exit the phase if code does not compile.** This is a hard gate — no exceptions.
+
+```
+[IMPLEMENT] [7/8] Build & run verification... ✅
+```
+
+## Multi-machine Branching
+
+```
+Single repo:
+  main → feat/{feature} → feat/{feature}/epic-1 (Subagent A)
+                         → feat/{feature}/epic-2 (Subagent B)
+
+Multi-repo:
+  Subagent A: cd user-service && git checkout -b feat/{feature}
+  Subagent B: cd payment-service && git checkout -b feat/{feature}
+```
+
+## Output
+
+- `.vsaf/docs/features/{feature-name}/07-impl-plan.md` — task plan + TDD log
+- Code changes on feature branch
+- All tests GREEN
+- SonarQube metrics PASS (verified during coding)
+
+## Phase Exit Protocol
+
+In PHASE REPORT:
+- Done: N tasks completed, M tests written, K subagents dispatched
+- Result: all tests PASS/FAIL
+- SonarQube (New Code): {PASS/FAIL vs shared gate} — Issues={N}, Blocker={N}, Critical={N}, Major={N}, Code Smells={N}, Vulns={N}, Hotspots Reviewed={N}%, Duplication={N}%
+- SonarQube (Overall): {PASS/FAIL vs shared gate} — Bugs={N}, Code Smells={N}, Duplication={N}%, ratings={A..E}
+- Output files: `07-impl-plan.md`
+- Code changes: {list files changed}
+- Suggestions: [1] Phase 7 Review (`/sdlc-review`) [2] Save artifacts
+
+Update `.vsaf/docs/STATUS.md`.
+
+**Notify the user:**
+> Artifacts have been saved. If the session is interrupted, open a new session and run the next phase — data is safe.
+
+## Rules
+
+- DO NOT write code without a failing test first (#2 TDD)
+- **MANDATORY** use `/superpowers:subagent-driven-development` — do not run sequential
+- **SonarQube rules apply DURING coding** — do not wait for review
+- Follow the Conflict Map — only modify files assigned to your epic
+- 3-strike rule: task fails 3 times → STOP, escalate
+- Impact analysis MUST run before each commit
+- Smart Zone: clear context every 5 tasks (#4)
+- **Code MUST compile successfully** — hard gate, no exceptions
+- **Recommend Docker** if runtime is missing or containerization is not set up
+- ⛔ DO NOT modify `graphify-out/` or `.gitnexus/`

package/skills/sdlc/implement/checkpoint/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-checkpoint
+description: "Implement 3.5/8 — checkpoint review"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 3.5/8 — checkpoint review
+
+@include(step.md)

package/skills/sdlc/implement/checkpoint/step.md

@@ -0,0 +1,20 @@
+### Step 3.5: Checkpoint Review (every 3-5 tasks)
+
+```
+[IMPLEMENT] [3.5/8] Checkpoint review... ⏳
+```
+
+After every 3-5 completed tasks: invoke `/bmad-checkpoint-preview` (human-in-the-loop walkthrough).
+
+Purpose: pause and let the user review progress before continuing.
+
+The checkpoint will:
+- Summarize: what was done, which files changed, current tests status
+- Highlight: points of concern, potential issues
+- Ask user: continue / adjust / stop?
+
+**Skip checkpoint if** the total plan has fewer than 5 tasks — checkpoint only at the end in that case.
+
+```
+[IMPLEMENT] [3.5/8] Checkpoint review... ✅
+```

package/skills/sdlc/implement/debug/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-debug
+description: "Implement 5/8 — debug if needed"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 5/8 — debug if needed
+
+@include(step.md)

package/skills/sdlc/implement/debug/step.md

@@ -0,0 +1,25 @@
+### Step 5: Debug (if needed)
+
+```
+[IMPLEMENT] [5/8] Debug (if there are test failures)... ⏳
+```
+
+Use `/superpowers:systematic-debugging` — when a test does not turn GREEN:
+- Hypothesis → Experiment → Conclusion
+- If it fails 3 times → STOP, escalate
+
+**Scope-drift detection:**
+
+If during implementation you detect the feature requires CHANGES NOT IN THE SRS:
+1. Invoke `/bmad-correct-course` — assess impact + propose adjustments
+2. If requirements have genuinely changed:
+   - STOP implementation
+   - Update SRS first via `/sdlc-srs` EDIT mode
+   - Re-run `/sdlc-test-design` to generate new test cases
+   - Restart Phase 6 from Step 3
+3. If only minor adjustments needed: document the adjustment in `07-impl-plan.md` §Scope Adjustments and continue
+4. If unclear whether scope changed: STOP and present to user — let them decide
+
+```
+[IMPLEMENT] [5/8] Debug (if there are test failures)... ✅
+```

package/skills/sdlc/implement/impact/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-impact
+description: "Implement 6/8 — impact verification"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 6/8 — impact verification
+
+@include(step.md)

package/skills/sdlc/implement/impact/step.md

@@ -0,0 +1,12 @@
+### Step 6: Impact Verification
+
+```
+[IMPLEMENT] [6/8] Impact verification via GitNexus... ⏳
+```
+
+Use GitNexus `impact` — verify no other code is broken.
+Use GitNexus `rename` — safe multi-file refactoring if needed.
+
+```
+[IMPLEMENT] [6/8] Impact verification via GitNexus... ✅
+```

package/skills/sdlc/implement/plan/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-plan
+description: "Implement 3/8 — task planning"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 3/8 — task planning
+
+@include(step.md)

package/skills/sdlc/implement/plan/step.md

@@ -0,0 +1,13 @@
+### Step 3: Task Planning
+
+```
+[IMPLEMENT] [3/8] Task planning from testcases + ADR... ⏳
+```
+
+Use `/superpowers:writing-plans` — create granular task plan from testcases + ADR.
+Each task maps to ≥1 FR/NFR.
+Write to `07-impl-plan.md`.
+
+```
+[IMPLEMENT] [3/8] Task planning from testcases + ADR... ✅
+```

package/skills/sdlc/implement/prereq/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: sdlc-implement-prereq
+description: "Implement 1/8 — input artifacts"
+version: 1.0.0
+author: "@ngocsangairvds/vsaf"
+---
+
+# Implement 1/8 — input artifacts
+
+@include(step.md)

package/skills/sdlc/implement/prereq/step.md

@@ -0,0 +1,21 @@
+## Phase Entry Protocol
+
+```
+[IMPLEMENT] [1/8] Checking input artifacts... ⏳
+```
+
+1. Input:
+   - `.vsaf/docs/features/{feature-name}/06-testcases.md`
+   - `.vsaf/docs/features/{feature-name}/03-adr.md`
+   - `.vsaf/docs/features/{feature-name}/04-epics.md`
+2. Verify ALL 3 files exist:
+   - Any file missing → Ask: "File not found. Have you pulled it yet?"
+3. Read `.vsaf/docs/STATUS.md`
+4. Read `CONTEXT.md`
+5. Query `graph.json` for code structure
+
+```
+[IMPLEMENT] [1/8] Checking input artifacts... ✅
+```
+
+**Note:** This phase MUST run via `/superpowers:subagent-driven-development` — dispatch parallel subagents for each epic according to the Conflict Map in `04-epics.md`.