@teevee98/synapse-hub 4.1.4 → 4.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: failure-autopsy-and-healing
3
3
  description: "Triage test failures from JUnit XML/screenshots and heal broken Page Class locators. Use when diagnosing failed test runs and producing closed-loop healing plans."
4
+ category: verification_and_resilience
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Failure Autopsy & Auto-Healing (Diagnostic & Self-Healing Engine)
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Triage test failures from JUnit XML/screenshots and heal broken Page Class locators. Use when diagnosing failed test runs and producing closed-loop healing plans.
20
+ - **Activation Scope:** Domain workflows for `06-healing-and-resilience` involving `failure-autopsy-and-healing`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT attempt locator healing without inspecting live DOM or accessibility tree states.
28
+ - Do NOT inject brittle positional XPaths as healed locators.
29
+ - Do NOT mask underlying application bugs as locator failures.
30
+ - **Sibling Skill Boundaries:**
31
+ - agentless-qa-repair executes rapid minimal diff patching; failure-autopsy-and-healing conducts comprehensive failure analysis and AOM locator healing.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for diagnosing batch test execution failures across automated test cases, performing visual autopsies via `Screenshots/FAILED_*.png`, parsing `JUnit_Report.xml`, and healing Page Classes (`Keywords/<namespace>/pages/*.groovy` or `pages/*.ts`) in place.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Five-Step Enterprise Autopsy Protocol
41
+ ### Five-Step Enterprise Autopsy Protocol
13
42
 
14
43
  ```mermaid
15
44
  flowchart LR
@@ -20,10 +49,11 @@ flowchart LR
20
49
  ```
21
50
 
22
51
  1. **Zero-Token Triage:** Pinpoint failed line and cause instantly (<50 tokens):
23
- ```bash
52
+ <!-- classification: illustrative -->
53
+ ```bash
24
54
  python tools/pinpoint_failure.py
25
55
  # or bash .agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh
26
- ```
56
+ ```
27
57
  2. **Visual Autopsy:** Inspect the latest error screenshot to immediately detect: disabled buttons, missing required fields, UI overlaps, or obscuring modal backdrops.
28
58
  3. **XML Parsing:** Extract stacktrace and exception messages from `Reports/<Timestamp>/JUnit_Report.xml` or Playwright test results.
29
59
  4. **In-Place Healing:** Update the corresponding Page Class in `Keywords/<project_namespace>/pages/` or `pages/`.
@@ -31,7 +61,7 @@ flowchart LR
31
61
 
32
62
  ---
33
63
 
34
- ## 2. Dynamic Module & Page Class Mapping Architecture
64
+ ### Dynamic Module & Page Class Mapping Architecture
35
65
 
36
66
  | Functional Module Category | Target Page Class to Heal | Common Failure Vector | Recommended Auto-Heal Strategy |
37
67
  | :--- | :--- | :--- | :--- |
@@ -45,15 +75,15 @@ flowchart LR
45
75
 
46
76
  ---
47
77
 
48
- ## 3. Reference Documentation
78
+ ### Reference Documentation
49
79
 
50
80
  - [**Diagnostic & Healing Matrix (`healing_matrix.md`)**](references/healing_matrix.md): Concrete code prescriptions for disabled buttons, boundary overlaps, `ElementClickInterceptedException`, `StaleElementReferenceException`, and 4 flaky test root causes.
51
- - [**Fast-Fix Triad & Runtime Helper (`tools/browser_helpers.js`)**](../../../tools/browser_helpers.js): In-browser diagnosis engine via `window.__qa` (`audit`, `heal`, `clickSafe`, `hud`).
81
+ - **Fast-Fix Triad & Runtime Helper (`tools/browser_helpers.js`):** In-browser diagnosis engine via `window.__qa` (`audit`, `heal`, `clickSafe`, `hud`).
52
82
  - **Automated Triage Script:** `python tools/pinpoint_failure.py` and `scripts/triage_failures.sh`.
53
83
 
54
84
  ---
55
85
 
56
- ## 4. Boundary vs `self-healing-locator` (Do Not Confuse)
86
+ ### Boundary vs `self-healing-locator` (Do Not Confuse)
57
87
 
58
88
  - **This skill** = the general physician: accepts ANY failed test run, performs
59
89
  root-cause analysis (JUnit XML, logs, screenshots), queries the memory cache,
@@ -64,3 +94,19 @@ flowchart LR
64
94
  this skill's plan when the RCA concludes "locator drift".
65
95
  - Rule of thumb: if the failure reason is not yet known, start here; only after
66
96
  the RCA says "locator broke" hand the repair to `self-healing-locator`.
97
+
98
+ ---
99
+
100
+ ## 4. Verification Points & DoD
101
+
102
+ 1. Failure autopsy categorizes failure root cause (AUT defect vs Locator drift vs Environment).
103
+ 2. Healed locators conform to 6-tier locator hierarchy and Clean POM standards.
104
+ 3. Healed tests pass dynamic verification runs.
105
+
106
+ ---
107
+
108
+ ## 5. Handoff Protocol
109
+
110
+ - **Deliverables:** Failure autopsy report, healed Page Class selectors, and verification run logs.
111
+ - **Next Subagent:** failure-analyst
112
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,17 +1,47 @@
1
1
  ---
2
2
  name: flaky-test-sentinel-and-quarantine
3
3
  description: "Detect non-deterministic flaky tests, calculate flakiness scores, and manage quarantine. Use when detecting flaky tests and managing quarantine lifecycles."
4
+ category: verification_and_resilience
5
+ version: "1.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Flaky Test Sentinel & Quarantine Protocol
7
12
 
8
- > **Purpose:** Master flaky test governance, automated quarantine isolation, and non-deterministic test remediation. Eliminates false-positive CI/CD pipeline blockers by identifying unstable tests through repeated execution ($N=5$), moving them into isolated quarantine suites, and tracking remediation until graduation.
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Use when detecting intermittent or non-deterministic test failures, calculating flakiness scores across repeated test executions ($N \ge 5$), managing test quarantine isolation, or tracking test graduation.
20
+ - **Activation Scope:**
21
+ - Test suites exhibiting non-deterministic pass/fail outcomes without code modifications.
22
+ - CI/CD pipeline stabilization via quarantine tagging (`@quarantine`).
23
+ - Quarantine lab execution and root-cause analysis.
24
+
25
+ ---
26
+
27
+ ## 2. Non-Goals & Boundary Constraints
28
+
29
+ - **What NOT to do:**
30
+ - Do NOT permanently silence or ignore flaky tests; quarantined tests must be monitored and scheduled for graduation.
31
+ - Do NOT use static delays (`Thread.sleep`, `time.sleep`) as a quick fix for flakiness.
32
+ - Do NOT make absolute stability guarantees; use empirical flakiness scoring and pass rate heuristics.
33
+ - **Sibling Skill Boundaries:**
34
+ - `failure-autopsy-and-healing`: Focuses on deep autopsy of deterministic single-run failures and locator self-healing.
35
+ - `systematic-debugging`: Governs root-cause investigation across general code and test defects.
36
+ - `flaky-test-sentinel-and-quarantine` (this skill): Manages multi-run detection, flakiness classification, quarantine isolation, and the graduation gate.
9
37
 
10
38
  ---
11
39
 
12
- ## 1. The Flaky Test Dilemma & The 5-Stage Quarantine Lifecycle
40
+ ## 3. Ordered Execution Workflow
13
41
 
14
- In large enterprise test suites (hundreds to thousands of test cases), non-deterministic tests ("flaky tests" that intermittently pass and fail without code changes) erode trust in CI/CD, slow down deployments, and cause developers to ignore test results.
42
+ ### Phase 1: Detection Engine & Quarantine Lifecycle
43
+
44
+ In large enterprise test suites, non-deterministic tests erode trust in CI/CD and slow down deployments. The 5-stage quarantine lifecycle isolates unstable tests while preserving delivery velocity:
15
45
 
16
46
  ```mermaid
17
47
  flowchart TD
@@ -21,9 +51,7 @@ flowchart TD
21
51
  D --> E["<b>5. Graduation DoD Gate</b><br/>Must achieve 10/10 consecutive passes<br/>Graduates back to main"]
22
52
  ```
23
53
 
24
- ---
25
-
26
- ## 2. Flakiness Scoring Formula & Classification
54
+ ### Phase 2: Flakiness Scoring Formula & Classification
27
55
 
28
56
  $$P = \frac{\text{Passed Executions}}{N} \times 100\% \quad \text{where } N \ge 5$$
29
57
 
@@ -36,11 +64,11 @@ $$\text{Flip Rate} = \frac{\text{Status Transitions (Pass} \leftrightarrow \text
36
64
  | **SEVERE FLAKE** | $P < 80\%$ | $\ge 2$ flips | **Immediate Quarantine Tagging (`@quarantine`)** | Excluded from PR merge blocker |
37
65
  | **DEAD TEST / BROKEN**| $0\%$ | 0 flips | File critical AUT/Test bug defect | Regular test failure |
38
66
 
39
- ---
67
+ ### Phase 3: Quarantine Tagging & Execution Strategies
40
68
 
41
- ## 3. Quarantine Tagging & Execution Strategies
69
+ #### Playwright / TypeScript Quarantine Tagging
42
70
 
43
- ### Playwright / TypeScript Quarantine Tagging
71
+ <!-- classification: illustrative -->
44
72
  ```typescript
45
73
  import { test, expect } from '@playwright/test';
46
74
 
@@ -51,26 +79,26 @@ import { test, expect } from '@playwright/test';
51
79
  test('TC-104: Submit monthly reconciliation report @quarantine', async ({ page }) => {
52
80
  // Test code remains intact for debugging
53
81
  await page.goto('/reports/reconciliation');
54
- // ...
82
+ await expect(page.locator('.reconciliation-panel')).toBeVisible();
55
83
  });
56
84
  ```
57
85
 
58
- ### CI/CD Filter Configuration
86
+ #### CI/CD Filter Configuration
87
+
88
+ <!-- classification: illustrative -->
59
89
  ```bash
60
- # 1. Main PR Blocker Suite: Runs ONLY 100% stable tests (Zero Flaky Disruptions)
90
+ # 1. Main PR Blocker Suite: Runs stable tests to minimize flaky disruptions
61
91
  npx playwright test --grep-invert "@quarantine"
62
92
 
63
93
  # 2. Nightly Quarantine Lab: Runs quarantined tests to collect diagnostics & heal
64
94
  npx playwright test --grep "@quarantine" --reporter=json
65
95
  ```
66
96
 
67
- ---
68
-
69
- ## 4. Automated Multi-Run Flakiness Detector Tool
97
+ ### Phase 4: Automated Multi-Run Flakiness Detector Tool
70
98
 
71
99
  This repository provides an automated flakiness analyzer in `tools/flaky_detector.py`.
72
100
 
73
- ### Running 5-Iteration Flakiness Benchmark
101
+ <!-- classification: illustrative -->
74
102
  ```bash
75
103
  # Run a specific test script 5 consecutive times to benchmark stability
76
104
  synapse flaky --repeat 5 --cmd "npm test -- tests/e2e/TC-104.spec.ts"
@@ -79,7 +107,9 @@ synapse flaky --repeat 5 --cmd "npm test -- tests/e2e/TC-104.spec.ts"
79
107
  synapse flaky --reports "reports/**/junit*.xml"
80
108
  ```
81
109
 
82
- Output Report (`reports/quarantine_board.json`):
110
+ Reference quarantine registry schema (see `examples/quarantine_registry.json` and generated `reports/quarantine_board.json`):
111
+
112
+ <!-- classification: illustrative -->
83
113
  ```json
84
114
  {
85
115
  "test_id": "TC-104",
@@ -93,9 +123,7 @@ Output Report (`reports/quarantine_board.json`):
93
123
  }
94
124
  ```
95
125
 
96
- ---
97
-
98
- ## 5. Root-Cause Remediation Guide (Heal & Graduate)
126
+ ### Phase 5: Root-Cause Remediation (Heal & Graduate)
99
127
 
100
128
  | Flakiness Root Cause | Anti-Pattern | Mandatory Remediation |
101
129
  | :--- | :--- | :--- |
@@ -106,9 +134,17 @@ Output Report (`reports/quarantine_board.json`):
106
134
 
107
135
  ---
108
136
 
109
- ## 6. Graduation Definition of Done (DoD) Gate
137
+ ## 4. Verification Points & DoD
110
138
 
111
139
  Before removing the `@quarantine` tag and restoring a test to the main PR suite:
112
140
  1. **Verification Run:** The healed test must execute **10 consecutive iterations** in headless mode with **100% Pass Rate** (`10/10 PASS`).
113
- 2. **Code Standards:** 100% UTF-8 No BOM, Clean POM flat architecture, zero hardcoded XPaths.
114
- 3. **Artifact Update:** Update `reports/quarantine_board.json` to mark status as `GRADUATED`.
141
+ 2. **Code Standards:** 100% UTF-8 No BOM, Clean POM flat architecture, zero hardcoded XPaths, dynamic smart waits.
142
+ 3. **Artifact Update:** Update `reports/quarantine_board.json` (or `examples/quarantine_registry.json`) to mark status as `GRADUATED`.
143
+
144
+ ---
145
+
146
+ ## 5. Handoff Protocol
147
+
148
+ - **Deliverables:** Updated test file with `@quarantine` tag added or removed, flakiness detection log, and `reports/quarantine_board.json`.
149
+ - **Next Subagent:** Pass quarantined tests to `failure-analyst` for root-cause diagnosis or to `quality-gatekeeper` for graduation sign-off.
150
+ - **Output Format:** JSON flakiness report with pass rate and flip count metrics.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: self-healing-locator
3
3
  description: "Heal broken locators using semantic AOM diffing with Role, Label, and TestId hierarchy. Use when locators break and automated healing strategies are needed."
4
+ category: verification_and_resilience
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Self-Healing Locator Skill — Token-Efficient AOM Diffing
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Heal broken locators using semantic AOM diffing with Role, Label, and TestId hierarchy. Use when locators break and automated healing strategies are needed.
20
+ - **Activation Scope:** Domain workflows for `06-healing-and-resilience` involving `self-healing-locator`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT fall back to brittle positional XPaths when primary locators fail.
28
+ - Do NOT hardcode healed locators in test scripts; encapsulate updates inside Page Classes.
29
+ - Do NOT silently update locators without logging the drift and confidence score.
30
+ - **Sibling Skill Boundaries:**
31
+ - failure-autopsy-and-healing handles full failure autopsies; self-healing-locator focuses specifically on runtime and static selector recovery using AOM diffing.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  This skill provides an automated, token-conservative mechanism to diagnose, diff, and repair broken web element locators across web applications without overwhelming the LLM context window with raw HTML dumps.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. The Token Conservation Principle
41
+ ### The Token Conservation Principle
13
42
 
14
43
  - **Raw HTML DOM Problem:** Dumping a complete HTML webpage into the prompt can consume 50,000 to 150,000 tokens, degrading AI reasoning and triggering context rot.
15
44
  - **AOM Subtree Solution:** Extract exclusively the **Accessibility Object Model (AOM)** tree or a 2-hop semantic DOM subtree surrounding the target element, consuming under **500 tokens**.
@@ -24,7 +53,7 @@ flowchart LR
24
53
 
25
54
  ---
26
55
 
27
- ## 2. Master Locator Ranking Hierarchy
56
+ ### Master Locator Ranking Hierarchy
28
57
 
29
58
  When searching for a replacement locator, evaluate candidates in this strict priority order:
30
59
 
@@ -44,10 +73,11 @@ When searching for a replacement locator, evaluate candidates in this strict pri
44
73
 
45
74
  ---
46
75
 
47
- ## 3. In-Browser AOM Probing Snippet
76
+ ### In-Browser AOM Probing Snippet
48
77
 
49
78
  Execute this compact JavaScript probe via Playwright or Chrome DevTools to locate the target node without dumping HTML:
50
79
 
80
+ <!-- classification: illustrative -->
51
81
  ```javascript
52
82
  // Extract interactive elements tree scoped to active modal or container
53
83
  () => {
@@ -65,7 +95,7 @@ Execute this compact JavaScript probe via Playwright or Chrome DevTools to locat
65
95
 
66
96
  ---
67
97
 
68
- ## 4. Healing Execution Checklist
98
+ ### Healing Execution Checklist
69
99
 
70
100
  1. **Verify Uniqueness:** Ensure the candidate locator matches exactly 1 element on the live DOM.
71
101
  2. **Encapsulate in Page Class:** Update the locator constant or private selector inside the relevant Page Class (e.g. `BasePage` or domain Page Class).
@@ -73,7 +103,7 @@ Execute this compact JavaScript probe via Playwright or Chrome DevTools to locat
73
103
 
74
104
  ---
75
105
 
76
- ## 5. Boundary vs `failure-autopsy-and-healing`
106
+ ### Boundary vs `failure-autopsy-and-healing`
77
107
 
78
108
  - **This skill** = a locator-repair cascade (cache → testid → text-semantic →
79
109
  geometric relative match), used when the diagnosis "stale/broken locator"
@@ -84,3 +114,19 @@ Execute this compact JavaScript probe via Playwright or Chrome DevTools to locat
84
114
  skill does not touch).
85
115
  - Chain of custody: autopsy RCA → "locator drift" verdict → this skill repairs
86
116
  → autopsy re-runs the healed test to close the loop.
117
+
118
+ ---
119
+
120
+ ## 4. Verification Points & DoD
121
+
122
+ 1. Healed selector matches target element with $\ge 80\%$ confidence.
123
+ 2. Locator update strictly preserves Clean POM encapsulation in Page Classes.
124
+ 3. Verification run confirms successful element interaction with healed selector.
125
+
126
+ ---
127
+
128
+ ## 5. Handoff Protocol
129
+
130
+ - **Deliverables:** Updated Page Class selector definitions, healing confidence log, and test verification output.
131
+ - **Next Subagent:** failure-analyst / pom-crafter
132
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,23 +1,53 @@
1
1
  ---
2
2
  name: systematic-debugging
3
3
  description: "Investigate root cause through four disciplined phases before proposing any fix for a test failure, bug, or unexpected behavior. Use when a test fails, a defect appears, or a fix attempt has already failed and guessing is tempting."
4
+ category: verification_and_resilience
5
+ version: "1.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Systematic Debugging — Enterprise Root-Cause Standard
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Investigate root cause through four disciplined phases before proposing any fix for a test failure, bug, or unexpected behavior. Use when a test fails, a defect appears, or a fix attempt has already failed and guessing is tempting.
20
+ - **Activation Scope:** Domain workflows for `06-healing-and-resilience` involving `systematic-debugging`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT propose fixes before completing root-cause investigation (The Iron Law).
28
+ - Do NOT make multiple speculative changes simultaneously; test one hypothesis at a time.
29
+ - Do NOT modify out-of-scope files or write dummy bypasses to force test passes.
30
+ - **Sibling Skill Boundaries:**
31
+ - agentless-qa-repair and failure-autopsy handle automated patch synthesis; systematic-debugging governs human-agent scientific diagnostic protocol.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for failure investigation in test automation: always find root cause before attempting fixes. Symptom fixes are failure.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. The Iron Law
41
+ ### The Iron Law
13
42
 
14
- ```
43
+ <!-- classification: illustrative -->
44
+ ```text
15
45
  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
16
46
  ```
17
47
 
18
48
  If Phase 1 is not complete, proposing fixes is prohibited. This applies ESPECIALLY when: under time pressure (emergencies make guessing tempting), a "quick fix" seems obvious, or previous fixes did not work.
19
49
 
20
- ## 2. The Four Phases
50
+ ### The Four Phases
21
51
 
22
52
  ```mermaid
23
53
  flowchart TD
@@ -53,7 +83,7 @@ flowchart TD
53
83
  4. **If the fix does not work:** STOP. Count attempts. Fewer than 3 → return to Phase 1 with the new information.
54
84
  5. **If 3+ fixes failed:** question the architecture, not the code — each fix revealing a new problem elsewhere is the signature of a wrong pattern. Discuss with the user before a fourth attempt.
55
85
 
56
- ## 3. Hub Tooling Chain
86
+ ### Hub Tooling Chain
57
87
 
58
88
  | Step | Tool | Role in investigation |
59
89
  |---|---|---|
@@ -65,7 +95,7 @@ flowchart TD
65
95
 
66
96
  Escalation order: `failure-analyst` performs the autopsy; `quality-gatekeeper` re-verifies after the fix lands.
67
97
 
68
- ## 4. Red Flags — STOP and Return to Phase 1
98
+ ### Red Flags — STOP and Return to Phase 1
69
99
 
70
100
  - "Quick fix for now, investigate later"
71
101
  - "Just try changing X and see if it works"
@@ -75,11 +105,11 @@ Escalation order: `failure-analyst` performs the autopsy; `quality-gatekeeper` r
75
105
  - "One more fix attempt" after 2+ failures
76
106
  - Each fix revealing a new problem in a different place (architecture question)
77
107
 
78
- ## 5. When Investigation Finds No Root Cause
108
+ ### When Investigation Finds No Root Cause
79
109
 
80
110
  If disciplined investigation proves the issue is genuinely environmental or timing-dependent: document what was investigated, implement appropriate handling (retry, timeout, error message), add monitoring for future investigation — and remember: most "no root cause" conclusions are incomplete investigation. Hand residual non-determinism to `flaky-test-sentinel-and-quarantine` for scoring and quarantine instead of declaring it unsolvable.
81
111
 
82
- ## 6. Boundary vs Sibling Skills (Do Not Confuse)
112
+ ### Boundary vs Sibling Skills (Do Not Confuse)
83
113
 
84
114
  | Sibling | Owns | Hand-off |
85
115
  |---|---|---|
@@ -88,13 +118,29 @@ If disciplined investigation proves the issue is genuinely environmental or timi
88
118
  | `flaky-test-sentinel-and-quarantine` | Flakiness scoring and quarantine lifecycle | Receives non-reproducible findings after Phase 1 |
89
119
  | `self-healing-locator` | Semantic locator healing | Consumes the verified root cause for locator-class defects |
90
120
 
91
- ## 7. Reference Documentation
121
+ ### Reference Documentation
92
122
 
93
123
  - `python3 tools/pinpoint_failure.py <report>` — first command on any failed run.
94
124
  - `python3 tools/auto_heal.py` — closed-loop triage after isolation.
95
125
  - `python3 tools/cache_resolver.py query "<error message>"` — 0-token known-defect lookup.
96
126
  - [Four-phase worked case (`four_phase_case.md`)](examples/four_phase_case.md): a timeout failure traced to root cause.
97
127
 
98
- ## 8. Attribution
128
+ ### Attribution
99
129
 
100
130
  Adapted from **superpowers** skill `systematic-debugging` (https://github.com/obra/superpowers) — MIT License, Copyright (c) 2025 Jesse Vincent. The Iron Law, four-phase process, 3-fix architecture rule, and rationalization guardrails are re-scoped for enterprise QA automation in Synapse Hub; wording, structure, and tooling chain modified.
131
+
132
+ ---
133
+
134
+ ## 4. Verification Points & DoD
135
+
136
+ 1. Phase 1 root-cause investigation identifies exact failure trigger and line span.
137
+ 2. Single minimal hypothesis tested with isolated modification.
138
+ 3. Reproduction test confirms defect is resolved without regression.
139
+
140
+ ---
141
+
142
+ ## 5. Handoff Protocol
143
+
144
+ - **Deliverables:** Root-cause investigation log, hypothesis testing records, and minimal verified patch.
145
+ - **Next Subagent:** failure-analyst / pom-crafter
146
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,24 +1,54 @@
1
1
  ---
2
2
  name: test-driven-development
3
3
  description: "Enforce the RED-GREEN-REFACTOR cycle: no production or automation code is written before a failing test exists and has been watched failing. Use when implementing new helpers, Page Class logic, bug fixes, or any behavior change in test codebases."
4
+ category: verification_and_resilience
5
+ version: "1.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Test-Driven Development — Enterprise Red-Green-Refactor Standard
7
12
 
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Enforce the RED-GREEN-REFACTOR cycle: no production or automation code is written before a failing test exists and has been watched failing. Use when implementing new helpers, Page Class logic, bug fixes, or any behavior change in test codebases.
20
+ - **Activation Scope:** Domain workflows for `06-healing-and-resilience` involving `test-driven-development`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT write production implementation code before authoring a failing test (The Iron Law).
28
+ - Do NOT write tests that assert trivialities or implementation details; test observable behavior.
29
+ - Do NOT skip the Refactor phase of the Red-Green-Refactor cycle.
30
+ - **Sibling Skill Boundaries:**
31
+ - lean-code-ladder governs code minimization; test-driven-development governs the Red-Green-Refactor authoring discipline.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for writing test-automation and tool code test-first: write the test, watch it fail for the right reason, write minimal code to pass, then refactor while staying green.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. The Iron Law
41
+ ### The Iron Law
13
42
 
14
- ```
43
+ <!-- classification: illustrative -->
44
+ ```text
15
45
  NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
16
46
  ```
17
47
 
18
48
  - Code written before the test is deleted — not kept "as reference", not "adapted while writing tests". Delete means delete; implement fresh from the tests.
19
49
  - "Violating the letter of the rules is violating the spirit of the rules." Thinking "skip TDD just this once" is rationalization, not judgment.
20
50
 
21
- ## 2. The Cycle
51
+ ### The Cycle
22
52
 
23
53
  ```mermaid
24
54
  flowchart LR
@@ -45,7 +75,7 @@ flowchart LR
45
75
 
46
76
  - Remove duplication, improve names, extract helpers. Keep tests green; add no behavior.
47
77
 
48
- ## 3. Good Tests
78
+ ### Good Tests
49
79
 
50
80
  | Quality | Good | Bad |
51
81
  |---|---|---|
@@ -54,13 +84,13 @@ flowchart LR
54
84
  | Intent-revealing | Demonstrates the desired API | Obscures what the code should do |
55
85
  | Honest | Asserts real behavior; you can name the production change that would make it fail | Asserts on mock behavior only |
56
86
 
57
- ## 4. Hub Integration
87
+ ### Hub Integration
58
88
 
59
89
  - **Fake-pass synergy:** test-first pairs with `python3 tools/infer_linter.py` (flags 0-assert and tautological tests) and Gate 8 — `python3 tools/micro_mutator.py` requires Mutation Score >= 80%, which a test written AFTER the code rarely achieves honestly.
60
90
  - **Bug fixes:** the bug reproduction IS the RED test. Never fix a bug without a test that fails before the fix and passes after.
61
91
  - **Locator logic:** selector helpers and Page Class methods follow the same cycle; live verification (Stage 2 of `playwright-live-interaction`, 100% hit rate under 200ms) is the RED check for locator changes.
62
92
 
63
- ## 5. Common Rationalizations (All Rejected)
93
+ ### Common Rationalizations (All Rejected)
64
94
 
65
95
  | Excuse | Reality |
66
96
  |---|---|
@@ -72,7 +102,7 @@ flowchart LR
72
102
  | "Test hard = skip" | Hard to test means hard to use; listen to the design signal. |
73
103
  | "TDD will slow me down" | TDD catches bugs before commit and lets you refactor without fear; the pragmatic shortcut is debugging in production. |
74
104
 
75
- ## 6. Red Flags — Stop and Start Over
105
+ ### Red Flags — Stop and Start Over
76
106
 
77
107
  - Code before test; test written after implementation
78
108
  - Test passes immediately on first run
@@ -81,7 +111,7 @@ flowchart LR
81
111
 
82
112
  All of these mean: delete the code and restart the cycle from RED.
83
113
 
84
- ## 7. Verification Checklist
114
+ ### Verification Checklist
85
115
 
86
116
  Before marking any implementation complete:
87
117
 
@@ -94,7 +124,7 @@ Before marking any implementation complete:
94
124
 
95
125
  Cannot check all boxes? The cycle was skipped — start over.
96
126
 
97
- ## 8. Boundary vs Sibling Skills (Do Not Confuse)
127
+ ### Boundary vs Sibling Skills (Do Not Confuse)
98
128
 
99
129
  | Sibling | Owns | Hand-off |
100
130
  |---|---|---|
@@ -103,12 +133,28 @@ Cannot check all boxes? The cycle was skipped — start over.
103
133
  | `antigravity-test-sentinel` | Hard completion blocking on gates | The sentinel enforces what this skill produces (fresh, watched, honest tests) |
104
134
  | `surgical-coding-principles` | Diff discipline | Goal-Driven Execution (principle 4) is operationalized by this cycle |
105
135
 
106
- ## 9. Reference Documentation
136
+ ### Reference Documentation
107
137
 
108
138
  - `python3 tools/infer_linter.py` — AST scan for fake passes and 0-assert tests.
109
139
  - `python3 tools/micro_mutator.py` — Gate 8 mutation floor (>= 80%) validating test honesty.
110
140
  - [Worked QA example (`red_green_refactor_qa.md`)](examples/red_green_refactor_qa.md): full cycle for a retry helper in a test utility.
111
141
 
112
- ## 10. Attribution
142
+ ### Attribution
113
143
 
114
144
  Adapted from **superpowers** skill `test-driven-development` (https://github.com/obra/superpowers) — MIT License, Copyright (c) 2025 Jesse Vincent. The Iron Law, RED-GREEN-REFACTOR cycle, and rationalization table are re-scoped for enterprise QA automation in Synapse Hub; wording, structure, and examples modified.
145
+
146
+ ---
147
+
148
+ ## 4. Verification Points & DoD
149
+
150
+ 1. Failing test authored first, proving absence or defect in capability (RED).
151
+ 2. Minimal implementation written to pass the test (GREEN).
152
+ 3. Code cleaned and refactored while maintaining passing test status (REFACTOR).
153
+
154
+ ---
155
+
156
+ ## 5. Handoff Protocol
157
+
158
+ - **Deliverables:** Test suite authored prior to code, minimal implementation diff, and test pass evidence.
159
+ - **Next Subagent:** pom-crafter / quality-gatekeeper
160
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.