@teevee98/synapse-hub 4.2.0 → 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 (107) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/cli.py +4 -4
  82. package/tools/core/bm25_retriever.py +1 -1
  83. package/tools/core/i18n.py +1 -1
  84. package/tools/core/provider_usage_adapter.py +66 -0
  85. package/tools/core/token_estimator.py +39 -1
  86. package/tools/count_tokens.py +2 -2
  87. package/tools/dashboard_generator.py +8 -8
  88. package/tools/db_sandbox.py +182 -43
  89. package/tools/distill_log.py +1 -1
  90. package/tools/distill_skill.py +17 -2
  91. package/tools/git_pre_commit_guard.py +190 -1
  92. package/tools/mcp_docx_server.py +1 -1
  93. package/tools/mcp_excel_server.py +1 -1
  94. package/tools/mcp_server.py +33 -5
  95. package/tools/micro_mutator.py +30 -1
  96. package/tools/pentest_scope_guard.py +288 -15
  97. package/tools/project_state.py +29 -5
  98. package/tools/reversible_sandbox.py +58 -13
  99. package/tools/rules_router.py +80 -27
  100. package/tools/skill_canonical_digest.py +60 -2
  101. package/tools/sync_agent_rules.py +187 -61
  102. package/tools/task_memory_manager.py +16 -1
  103. package/tools/ui_server.py +3 -1
  104. package/tools/update_sentinel.py +3 -3
  105. package/tools/validate_skills_schema.py +349 -56
  106. package/tools/verify_all.py +96 -2
  107. package/tools/welcome_page.py +1 -1
package/AGENTS.md CHANGED
@@ -5,83 +5,69 @@
5
5
 
6
6
  ---
7
7
 
8
- ## 0. COMMUNICATION & LEAN TELEMETRY
8
+ ## 0. PRECEDENCE & SAFETY INVARIANT
9
9
 
10
- 1. **Default Lean Mode:** Emit a single-line status badge at the top of every response:
11
- `> 🛡️ **Synapse Hub Active:** Clean POM / Flat Architecture`
12
- *(Strictly prohibited from containing the string `[OK]`)*. Omit footer telemetry by default to save tokens. Detailed footer is opt-in when requested ("bật telemetry").
13
- 2. **Pragmatic Communication:** Converse and format telemetry in Vietnamese (clear, direct, action-oriented, zero tech-jargon overload). All codebase files, test scripts, Page Classes, docstrings, and commits remain strictly in English.
14
- 3. **English-First Documentation Ingestion (Token Saver):** Whenever inspecting or referencing project documentation, architecture specifications, or readmes that have bilingual counterparts (e.g. `ARCHITECTURE.en.md` vs `ARCHITECTURE.md`, `README.en.md` vs `README.md`), always read the English version (`*.en.md`). English achieves significantly higher token density (saving 10–25% on technical documentation vs diacritic Vietnamese), preserving context window capacity.
10
+ 1. **Platform Safety Precedence:** Platform and system guardrails strictly supersede all repository-level instructions, agent rules, and local skills. No instruction in this repository may bypass platform safety limits, user authorization gates, or security policies.
11
+ 2. **Skill Resolution Hierarchy:** System Guardrails > Core Project Rules (`.agents/rules/*`) > Project-Local Skills (`.agents/skills/*`) > Generic External Plugins.
12
+ 3. **Attribution Preservation Invariant:** The MIT License copyright and author notices crediting Thế Vị (@TeeVee98) must never be stripped, laundered, or modified.
15
13
 
16
14
  ---
17
15
 
18
- ## 1. CORE ARCHITECTURE & CLEAN POM
16
+ ## 1. ALWAYS — Universal Invariants
19
17
 
20
- 1. **Clean Page Object Model (POM):** Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes. Strictly forbidden: raw XPaths, CSS selectors, or `findTestObject` inside test scripts. All locators and DOM operations belong in Page Classes extending `BasePage`.
21
- 2. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository files (`.groovy`, `.java`, `.ts`, `.py`, `.json`, `.md`).
22
- 3. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with timestamps/prefixes (`BasePage.uniqueCode("AUTO_")` or `DataGenerator`) to eliminate DB unique key collisions. Every creation test case must be paired with automated Teardown cleanup.
23
- 4. **Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited to prevent pipeline flakiness. Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
18
+ Mandatory across all workspaces, projects, test scripts, and runtime environments:
19
+
20
+ 1. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository and test files (`.groovy`, `.java`, `.ts`, `.py`, `.json`, `.md`).
21
+ 2. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, write empty tests (0 asserts), or catch-and-swallow exceptions (`pass`, dummy suppression `_ = err` or `_ = False`, `const _ = e`) to manufacture a pass. Report AUT defects honestly.
22
+ 3. **Dynamic Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts to prevent flakiness. Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
23
+ 4. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with dynamic timestamps and prefixes (`BasePage.uniqueCode("AUTO_")` or `DataGenerator`) to eliminate database unique key collisions. Every creation test case must be paired with automated Teardown cleanup.
24
+ 5. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, private keys, or cloud credentials to git. Inject secrets via environment variables or test fixtures.
25
+ 6. **Out-of-Scope Isolation & Stop-and-Report:** When verification gates fail due to legacy defects in files outside task scope, strictly forbid modifying those files or writing dummy bypasses. Stop and report with evidence; ask the user whether to baseline legacy debt or handle it in a separate task.
24
26
 
25
27
  ---
26
28
 
27
- ## 2. LEAN SENIOR DEV PROTOCOL (7-RUNG LADDER & YAGNI)
28
-
29
- You are a lazy senior developer. The best code is the code never written. Solve the whole problem with the least new code.
30
-
31
- 1. **Before You Write (Scope First):** Read the task and the code it touches. List callers, Page Classes, tests, fixtures, configs. Check what your change could break: data it would destroy or expose, callers that stop working. That is scope; extra features are not.
32
- 2. **The 7-Rung Ladder (Stop at the first rung that fully works):**
33
- - **Rung 1:** *Does it need to exist?* (YAGNI). Skip unrequested features, options, and speculative flexibility in one line.
34
- - **Rung 2:** *Already in this codebase?* Use existing helpers, Page Classes, BasePage methods, and patterns.
35
- - **Rung 3:** *Standard library?* Use language stdlib unless the project has its own equivalent.
36
- - **Rung 4:** *Platform or framework native?* Use test framework native features (Playwright auto-waiting, web-first assertions).
37
- - **Rung 5:** *An installed dependency?* Use existing dependencies. Never add a package for a few lines.
38
- - **Rung 6:** *Can it be one clear line?* Write a line a reader grasps at a glance.
39
- - **Rung 7:** *Otherwise:* Write the minimum complete code that works.
40
- 3. **Completeness & Execution Invariants:**
41
- - Be lazy about the solution, never about the change: finish every part the task needs, including callers, tests, and fixtures your change affects.
42
- - Zero unnecessary abstractions: no wrappers, speculative options, configs, or "for later" boilerplate nobody asked for. Deletion beats addition.
43
- - Shortest working diff wins. Comment only the "why" that code cannot show, in one concise line.
44
- - Root-cause bug fixing: grep every caller of touched functions before editing; fix the root cause once in shared code.
45
- - Code moved or merged strictly retains its error handling and validation.
46
- - Between options of equal size, choose the one that handles edge cases cleanly.
47
- - Lazy code without checks is unfinished: non-trivial logic (branch, loop, parser, auth, or money path) must leave one small test or self-check assertion before handoff. Trivial changes need none.
48
- - Pragmatic technical debt: Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
49
- - Out-of-Scope Pre-existing Failures (Stop & Report): When verification gates fail due to legacy defects in files outside task scope, strictly forbid modifying those files or writing dummy bypasses (`_ = err`, `_ = False`, empty catch). Stop and report with evidence; ask the user whether to baseline legacy debt or handle it in a separate task.
50
- 4. **Hard Floor (Never Cut):** Trust-boundary validation, error handling preventing data loss, security checks, accessibility (a11y), Clean POM separation, and anything explicitly requested.
51
- 5. **End-of-Turn Risk Note:** End every code response with one or two concise lines stating what was skipped or not checked and any risks the user must know.
29
+ ## 2. RECOMMENDED — Best Practices
52
30
 
53
- ### 2.1 Multi-Agent Handoff & Autonomy Protocols
54
- 1. **Rulings, Not Stalls (Jesse Vincent Protocol):** Autonomous subagents must never pause execution for trivial decisions. Record every judgment as:
55
- `Ruling: <what you decided> — <why> — <what it costs if wrong>` and proceed immediately.
56
- 2. **Self-Contained Task Briefings (Fan-Out Invariant):** When orchestrating subagents, prompts must be fully self-contained (`BRIEFING.md` format). Subagents cannot assume access to parent context.
57
- 3. **Doubt-Driven Falsification (Addy Osmani DDD):** Before declaring a test or locator verified, explicitly propose 3 falsification scenarios where the test passes while the feature is broken.
31
+ Applicable to QA engineering workflows, test development, and agent pair-programming:
32
+
33
+ 1. **Clean Page Object Model (POM) Flat Architecture:**
34
+ - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
35
+ - Strictly forbidden: raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
36
+ - All locators and DOM operations belong in Page Classes extending `BasePage`. Keep inheritance shallow (flat, max 1 level from `BasePage`).
37
+ 2. **Lean Senior Dev Protocol (7-Rung Ladder & YAGNI):**
38
+ - The best code is the code never written. Solve the whole problem with the least new code.
39
+ - Stop at the first rung that fully works: 1. Need to exist? (YAGNI) -> 2. Already in codebase? -> 3. Language stdlib? -> 4. Platform/framework native? -> 5. Installed dependency? -> 6. One clear line? -> 7. Minimum complete code.
40
+ - Zero unnecessary abstractions: no wrappers, speculative options, or boilerplate nobody asked for.
41
+ - Pragmatic technical debt: Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
42
+ 3. **Risk-Conditioned Autonomous Ceremonies:**
43
+ - **Jesse Vincent Rulings (`Ruling:`):** Mandatory for architectural forks, breaking changes, or non-trivial tradeoffs (`Ruling: <decision> — <why> — <cost if wrong>`). Subagents omit rulings for trivial typo, documentation, or minor locator fixes.
44
+ - **Addy Osmani Falsification (3 Scenarios):** Mandatory before certifying core test cases or complex locators (propose 3 realistic scenarios where code breaks while tests pass). Omit for trivial fixes (< 15 LOC).
45
+ 4. **Bilingual Communication & Lean Telemetry:**
46
+ - Emit single-line status badge at top of responses: `> 🛡️ **Synapse Hub Active:** Clean POM / Flat Architecture` (strictly prohibited from containing `[OK]`).
47
+ - Converse and format telemetry in Vietnamese (clear, direct, action-oriented, zero tech-jargon overload).
48
+ - Codebase files, test scripts, Page Classes, docstrings, and commits remain strictly in English.
49
+ 5. **English-First Documentation Ingestion (Token Saver):**
50
+ - Whenever inspecting documentation with bilingual counterparts (e.g. `ARCHITECTURE.en.md` vs `ARCHITECTURE.md`), always read the English version (`*.en.md`) to save 10–25% on technical documentation.
58
51
 
59
52
  ---
60
53
 
61
- ## 3. TRUTH ANCHOR & ON-DEMAND AUTONOMY
62
-
63
- 1. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, or catch-and-swallow exceptions (`pass`, dummy suppression `_ = err` or `_ = False`, `const _ = e`) to manufacture a pass. Report AUT defects honestly.
64
- 2. **No Lazy Truncation:** Always output complete, directly executable code (no `// TODO` or `// ... existing code ...`).
65
- 3. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, or private keys to git.
66
- 4. **Zero-Command Autonomous Activation (Never expect user to memorize CLI):**
67
- - New project / setup -> Autonomously run `tools/setup_project.py`.
68
- - User asks to audit project -> Autonomously run `tools/analyze_project.py`.
69
- - User asks to review diff/code -> Autonomously run `tools/senior_code_review.py`.
70
- - User asks to scan debt / shortcuts -> Autonomously run `tools/debt_harvester.py`.
71
- - Observer / Tradeoff check -> Autonomously run `tools/synapse_observer.py`.
72
- - Tone & anti-AI slop scan -> Autonomously run `tools/humanize_linter.py`.
73
- - Security audit & coverage ledger -> Autonomously run `tools/security_coverage_ledger.py`.
74
- - Test failure occurs in runner -> Autonomously run `tools/pinpoint_failure.py` / `tools/auto_heal.py`.
75
- - Verifying test assertion quality -> Autonomously run `tools/micro_mutator.py` (reject if Mutation Score < 80%).
76
- - Complex test failures / iterative self-healing -> Run `tools/auto_heal_reflexion.py` (Noah Shinn Reflexion K=3).
77
- - Reversible sandbox mutations / rollback -> Run `tools/reversible_sandbox.py`.
78
- - Querying / Storing verified PageClass library -> Run `tools/skill_vault.py`.
79
- - Vague requirements / story ambiguity -> Autonomously run `tools/interview_story.py`.
80
- - Optimizing assertions against surviving mutants -> Run `tools/textgrad_mutation_optimizer.py`.
81
- - User asks to push / release hub ("push lên", "push hub") -> Autonomously bump version based on changes via `tools/bump_version.py <patch|minor|major>` then run `tools/hub_publisher.py -y` (Push main + Tag + Release + Packages + NPM without stalling).
82
- - Task progress & compaction anchoring -> Autonomously run `tools/project_state.py`.
83
- - Before completing code tasks -> Autonomously run `tools/verify_all.py` (10 Quality Gates DoD). For quick fixes (< 15 lines of code), apply Fast-Track mode; for external target repos lacking `tools/`, gracefully fallback to native test runners (`npm test`, `pytest`, `mvn test`) per `.agents/rules/stack-auto-router.md` and `.agents/rules/systematic-debugging.md`.
84
- - Context-aware stack routing -> Strictly adhere to `.agents/rules/stack-auto-router.md` (Web/Mobile/Perf/Security scope) and 5-layer pentest safety gate (`.agents/rules/security_testing_rules.md`).
54
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
55
+
56
+ ⚠️ **CRITICAL SCOPE BOUNDARY:** The following CLI tools, verification harnesses, and automation scripts exist **ONLY** within the `Synapse-Hub` repository checkout. Target client projects and external repositories **DO NOT** possess these scripts and must use their own native test runners (`npm test`, `pytest`, `mvn test`):
57
+
58
+ 1. **Hub Operational Tools (Synapse-Hub Checkout Only):**
59
+ - Quality Gates DoD: `python tools/verify_all.py --mode hub`
60
+ - Release Publisher: `python tools/hub_publisher.py -y`
61
+ - Multi-Bridge Synchronizer: `python tools/sync_agent_rules.py`
62
+ - Mutation Testing Engine: `python tools/micro_mutator.py`
63
+ - Health Audit & Analysis: `python tools/analyze_project.py`
64
+ - Project State & Diagnostic: `python tools/project_state.py`
65
+ - Dynamic Auto-Healing: `python tools/auto_heal.py` / `python tools/pinpoint_failure.py`
66
+ - Security Scanner: `python tools/skillspector.py` / `python tools/pentest_scope_guard.py`
67
+ 2. **External Target Projects Fallback Invariant:**
68
+ - When mounted in a non-Hub repository, agents must NEVER invoke `tools/verify_all.py` or Synapse internal scripts.
69
+ - Use target project native commands defined in `package.json`, `pom.xml`, or `pyproject.toml` (`npm test`, `pytest`, `mvn test`).
70
+ - Bridge templates generated in `templates/ai_bridges/*` for client projects must never reference `tools/` scripts.
85
71
 
86
72
  ---
87
73
 
package/CLAUDE.md CHANGED
@@ -17,38 +17,52 @@ In accordance with the MIT License, the original copyright notice crediting **Th
17
17
  ---
18
18
 
19
19
  ## ⚡ Quick Commands
20
- - Verify 10 Quality Gates: `npx @teevee98/synapse-hub verify` (or `python tools/verify_all.py`)
21
- - Project Health Audit: `npx @teevee98/synapse-hub analyze` (or `python tools/analyze_project.py`)
22
- - Code Linter & Fake-Pass Sentinel: `npx @teevee98/synapse-hub lint` (or `python tools/infer_linter.py`)
20
+ - Verify 10 Quality Gates: `python tools/verify_all.py --mode hub` (or `npx @teevee98/synapse-hub verify`)
21
+ - Project Health Audit: `python tools/analyze_project.py`
22
+ - Code Linter & Fake-Pass Sentinel: `python tools/infer_linter.py`
23
23
  - Verify Author Attribution: `python tools/author_integrity.py`
24
24
  - Skill Security Audit: `python tools/skillspector.py .agents/skills`
25
+ - Multi-Bridge Sync: `python tools/sync_agent_rules.py`
25
26
 
26
27
  ---
27
28
 
28
- ## 🏛️ Core QA Automation Invariants (From AGENTS.md)
29
- 1. **Clean Page Object Model (POM):**
30
- - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
31
- - Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
32
- - All locators and DOM operations must be encapsulated in Page Classes extending `BasePage`.
33
-
34
- 2. **Truth Anchor (Zero Fake Passes):**
35
- - Never write empty assertions or tautological tests (0 asserts).
36
- - If a test fails due to an AUT defect, report it honestly. Never soften assertions or skip validation steps to fake a pass.
29
+ ## 0. PRECEDENCE & SAFETY INVARIANT
30
+ - Platform and system guardrails strictly override all repository-level instructions.
31
+ - Precedence: System Guardrails > Core Project Rules (`.agents/rules/*`) > Local Skills > Generic Plugins.
37
32
 
38
- 3. **Dynamic & Idempotent Test Data:**
39
- - Always randomize test entity codes with timestamps/prefixes (`AUTO_` + timestamp) to avoid DB unique constraint collisions.
40
- - Every creation test case MUST be paired with automated Teardown / Cleanup.
33
+ ---
41
34
 
42
- 4. **Synchronization & Smart Waits:**
43
- - Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts.
44
- - Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
35
+ ## 1. ALWAYS — Universal Invariants
36
+ 1. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository files.
37
+ 2. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, or catch-and-swallow exceptions to fake a pass.
38
+ 3. **Dynamic Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts. Use element visibility or `waitForLoadState('networkidle')`.
39
+ 4. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with dynamic timestamps/prefixes (`BasePage.uniqueCode("AUTO_")`). Pair creation with automated Teardown cleanup.
40
+ 5. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, or private keys.
41
+ 6. **Out-of-Scope Isolation:** When verification gates fail due to legacy defects in files outside task scope, stop and report; never touch out-of-scope files.
45
42
 
46
- 5. **Pragmatic Communication Protocol:**
47
- - Conversational responses, explanation, and telemetry MUST be in Vietnamese.
48
- - All codebase assets, test scripts, Page Classes, docstrings, and commits MUST remain strictly in English.
49
- - English-First Document Ingestion: When reading bilingual docs (e.g. ARCHITECTURE.en.md vs ARCHITECTURE.md), always read the English version (*.en.md) to save 50–65% BPE tokens.
43
+ ---
50
44
 
51
- 6. **Lean Senior Dev Protocol (The 7-Rung Ladder & YAGNI):**
45
+ ## 2. RECOMMENDED — Best Practices
46
+ 1. **Clean Page Object Model (POM) Flat Architecture:**
47
+ - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
48
+ - Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
49
+ - All locators and DOM operations belong in Page Classes extending `BasePage`. Keep inheritance flat (max 1 level).
50
+ 2. **Lean Senior Dev Protocol (7-Rung Ladder & YAGNI):**
52
51
  - The best code is the code never written. Solve the whole problem with the least new code.
53
52
  - Descend the 7-rung ladder: 1. Need to exist? 2. Already in codebase? 3. Standard library? 4. Platform native? 5. Installed dependency? 6. One clear line? 7. Minimum working code.
54
- - Any deliberate simplification gets an inline comment: `shortcut: <the limit>, <when to upgrade>`.
53
+ - Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
54
+ 3. **Risk-Conditioned Autonomous Ceremonies:**
55
+ - Jesse Vincent Rulings (`Ruling:`): Mandatory for architectural forks, breaking changes, or non-trivial tradeoffs. Omit for trivial doc/typo fixes.
56
+ - Addy Osmani Falsification (3 failure scenarios): Mandatory before certifying core test cases or complex locators.
57
+ 4. **Bilingual Communication & English-First Ingestion:**
58
+ - Conversational responses, explanation, and telemetry in Vietnamese.
59
+ - Codebase files, test scripts, Page Classes, docstrings, and commits strictly in English.
60
+ - Read English versions (`*.en.md`) when bilingual docs exist to preserve tokens.
61
+ ---
62
+
63
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
64
+ ⚠️ The following CLI tools exist ONLY in the Synapse-Hub repository checkout:
65
+ - Quality Gates DoD: `python tools/verify_all.py --mode hub`
66
+ - Release Publisher: `python tools/hub_publisher.py -y`
67
+ - Rule Synchronizer: `python tools/sync_agent_rules.py`
68
+ - Target external projects must use native runners (`npm test`, `pytest`, `mvn test`).
package/README.en.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  > **Core Mission:** A standalone linter and guardrail engine (zero external dependencies for core engine & DoD gates) safeguarding automated test suites when AI writes code — Automatically catching "fake-pass" tests (0 assertions, tautologies), eliminating fixed sleeps, compressing 95% of CI/CD log noise, and enforcing Clean POM architecture.
8
8
  > **Author:** Thế Vị ([@TeeVee98](https://github.com/TeeVee98)) | **License:** MIT License
9
- > **Version:** `v4.2.0` | **Scale:** 53 Standardized QA Skills, 9 Specialized AI Agents, 10 DoD Quality Gates.
9
+ > **Version:** `v4.2.1` | **Scale:** 53 Standardized QA Skills, 9 Specialized AI Agents, 10 DoD Quality Gates.
10
10
 
11
11
  [![npm version](https://img.shields.io/npm/v/@teevee98/synapse-hub.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@teevee98/synapse-hub)
12
12
  [![node version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
@@ -154,7 +154,7 @@ Every test code change must satisfy all 10 Quality Gates before pull request mer
154
154
  # Pre-commit hook (.pre-commit-config.yaml):
155
155
  repos:
156
156
  - repo: https://github.com/TeeVee98/Synapse-Hub
157
- rev: v4.2.0
157
+ rev: v4.2.1
158
158
  hooks:
159
159
  - id: synapse-lint
160
160
  - id: synapse-verify
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  > **Định vị cốt lõi:** Bộ Linter & Guardrails độc lập (zero external dependencies cho core engine & DoD gates) bảo vệ độ tin cậy của test suite khi AI viết code — Tự động bắt test "pass ảo" (0 assert, tautology), loại bỏ hoàn toàn sleep cố định, nén 95% log CI/CD, và chuẩn hóa cấu trúc Clean POM.
8
8
  > **Tác giả:** Thế Vị ([@TeeVee98](https://github.com/TeeVee98)) | **Giấy phép:** MIT License
9
- > **Phiên bản:** `v4.2.0` | **Quy mô:** 53 Kỹ năng QA, 9 Vai trò AI Agent, 10 Cổng kiểm định DoD.
9
+ > **Phiên bản:** `v4.2.1` | **Quy mô:** 53 Kỹ năng QA, 9 Vai trò AI Agent, 10 Cổng kiểm định DoD.
10
10
 
11
11
  [![npm version](https://img.shields.io/npm/v/@teevee98/synapse-hub.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@teevee98/synapse-hub)
12
12
  [![node version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
@@ -154,7 +154,7 @@ Mọi thay đổi mã nguồn kiểm thử đều được kiểm chứng qua 10
154
154
  # Pre-commit hook (.pre-commit-config.yaml):
155
155
  repos:
156
156
  - repo: https://github.com/TeeVee98/Synapse-Hub
157
- rev: v4.2.0
157
+ rev: v4.2.1
158
158
  hooks:
159
159
  - id: synapse-lint
160
160
  - id: synapse-verify
package/agentskills.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agentskills.io/schema/v1.json",
3
3
  "name": "Synapse-Hub",
4
- "version": "4.2.0",
4
+ "version": "4.2.1",
5
5
  "description": "Enterprise QA & Test Automation AI Skills Ecosystem — 53 skills organised across 11 Domain Packages adhering to Clean POM Flat Architecture.",
6
6
  "author": "Thế Vị (@TeeVee98)",
7
7
  "repository": "https://github.com/TeeVee98/Synapse-Hub",
@@ -3,7 +3,7 @@
3
3
  [🇻🇳 Tiếng Việt](ARCHITECTURE.md) | [🇬🇧 English Edition](ARCHITECTURE.en.md)
4
4
 
5
5
  > **Scope:** Enterprise Multi-Agent QA Hub
6
- > **Version:** `4.2.0` | **Status:** Active / Production Standard
6
+ > **Version:** `4.2.1` | **Status:** Active / Production Standard
7
7
 
8
8
  ---
9
9
 
@@ -3,7 +3,7 @@
3
3
  [🇻🇳 Tiếng Việt](ARCHITECTURE.md) | [🇬🇧 English Edition](ARCHITECTURE.en.md)
4
4
 
5
5
  > **Phạm vi:** Enterprise Multi-Agent QA Hub
6
- > **Version:** `4.2.0` | **Trạng thái:** Hoạt động / Tiêu chuẩn Sản xuất
6
+ > **Version:** `4.2.1` | **Trạng thái:** Hoạt động / Tiêu chuẩn Sản xuất
7
7
  > **Tác giả:** Thế Vị (@TeeVee98) | **Giấy phép:** MIT License
8
8
 
9
9
  ---
@@ -0,0 +1,44 @@
1
+ # Client Support & Host Interoperability Matrix
2
+
3
+ > **Synapse Hub Enterprise QA Automation Platform**
4
+ > **Author:** Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
5
+ > **License:** MIT License
6
+ > **Last Updated:** 2026-11-15
7
+
8
+ This document formalizes AI client and IDE host compatibility, distinguishing fully verified integration targets from experimental or unverified environments.
9
+
10
+ ---
11
+
12
+ ## 1. Comprehensive Host Support Matrix
13
+
14
+ | Client Host | Classification | Discovery / Hook Path | Scope / Capabilities | Limitations / Caveats |
15
+ | :--- | :---: | :--- | :--- | :--- |
16
+ | **Google Antigravity** | **Verified** | `.agents/skills/*/SKILL.md`<br/>`plugin.json`<br/>`agentskills.json` | Subagents, custom tools, rules router, MCP servers, episodic memory | Requires Antigravity environment |
17
+ | **Claude Code** | **Verified** | `CLAUDE.md`<br/>`templates/ai_bridges/CLAUDE.md` | Workspace instructions, CLI command execution, tool calls | In-context prompt adherence only; single agent loop |
18
+ | **Cursor IDE** | **Verified** | `.cursorrules`<br/>`.cursor/rules/synapse-qa.mdc` | Glob-matched file rules (`globs: **/*`), inline assistant, Composer | No background multi-agent swarm; single workspace |
19
+ | **GitHub Copilot** | **Verified** | `.github/copilot-instructions.md`<br/>`.github/instructions/*.instructions.md` | Path-specific instructions (`applyTo:`), Copilot Chat, CLI assistance | Chat and inline code suggestions only; no tool orchestration |
20
+ | **Windsurf** | **Verified** | `.windsurfrules`<br/>`templates/ai_bridges/windsurfrules` | Cascade engine directives, scratchpad, agent pair-programming | Single-agent chat flow |
21
+ | **Node.js / NPX CLI** | **Verified** | `bin/agent-qa.js`<br/>`package.json` | Global CLI execution (`agent-qa`, `npx @teevee98/synapse-hub`) | Requires Node.js >= 18.0.0 |
22
+ | **Python CLI** | **Verified** | `tools/cli.py`<br/>`pyproject.toml` | Full toolsuite execution (`agent-qa`, `synapse-hub`) | Requires Python >= 3.10 |
23
+ | **Codex** | **Unverified / Experimental** | Generic prompt fallback | Code generation & completion | No dedicated workspace instruction configuration file format |
24
+ | **OpenCode** | **Unverified / Experimental** | In-context prompt injection | Code generation & execution traces | Experimental; no standardized repository hook specification |
25
+ | **Goose** | **Unverified / Experimental** | Generic agent instructions | Task automation via MCP | Unverified CLI profile |
26
+ | **Devin / Cline** | **Unverified / Experimental** | Workspace instructions fallback | Autonomous web/CLI workflows | Unverified host configuration |
27
+
28
+ ---
29
+
30
+ ## 2. Integration Tiers & Host Requirements
31
+
32
+ ### Tier A: Native Multi-Agent & Rule Routing (Verified)
33
+ - **Google Antigravity:** Full support for 53 QA skills, subagent swarm orchestrator, rules routing, and MCP servers.
34
+ - **Node.js & Python CLIs:** Production package distributions supporting hermetic standalone execution.
35
+
36
+ ### Tier B: Synchronized IDE Bridge Directives (Verified)
37
+ - **Claude Code, Cursor IDE, Windsurf, GitHub Copilot:**
38
+ - Synchronized via `python tools/sync_agent_rules.py`.
39
+ - Single source of truth is `AGENTS.md`.
40
+ - Scope isolation: Template bridges deployed to client projects (`templates/ai_bridges/*`) omit Synapse-Hub-only CLI tools and reference project-native runners (`npm test`, `pytest`).
41
+
42
+ ### Tier C: Unverified / Experimental Hosts
43
+ - Host platforms that lack dedicated configuration hook formats (such as OpenAI Codex API, OpenCode, Goose, Devin, Cline) rely on prompt fallback or generic workspace ingestion.
44
+ - These hosts must be tested on a case-by-case basis before relying on autonomous execution.
@@ -0,0 +1,233 @@
1
+ # Side-Effecting Tools Inventory & Consent Boundary Specification
2
+
3
+ > **Status:** Active (Milestone 1 Remediation — P0 Granular Authorization, Consent Boundary & Path Containment)
4
+ > **Repository:** Synapse-Hub Enterprise QA Hub
5
+ > **Audience:** AI Agents, QA Automation Engineers, Security Auditors
6
+
7
+ ---
8
+
9
+ ## 1. Executive Summary & Security Mandate
10
+
11
+ In enterprise test automation and autonomous AI workflows, tools frequently execute active security probes, filesystem modifications, database wipe/restore routines, and external network egress. Without rigorous authorization and containment boundaries, autonomous execution poses significant operational and security risks:
12
+
13
+ 1. **Unbounded Network Egress:** Fuzzing probes, accessibility scanners, or issue-tracking bridges dispatching unauthorized HTTP/TCP traffic across intranet or external networks.
14
+ 2. **State Destruction & Pollution:** Database snapshot restoration or pollution purges overwriting production databases or uncontained SQLite files.
15
+ 3. **Filesystem Escape & Traversal:** Sandbox rollback handlers or mutation testing routines deleting or modifying files outside designated sandbox boundaries via directory traversal (`..`) or symlink escapes.
16
+ 4. **Stale or Replayed Authorization:** Operations executing under generic boolean flags (`consent=True`) or unauthenticated shared environment variables without cryptographic replay protection or expiration bounds.
17
+
18
+ ### Core Security Invariants
19
+ - **Default Deny:** Every side-effecting action is rejected unless an unexpired, unconsumed, cryptographically bounded `ConsentGrant` is provided.
20
+ - **Granular Binding:** Grants bind tightly to `action`, canonical `target`, `caller_session`, single-use `nonce`, and UTC `expiry`. HTTP operations must bind HTTP method and path patterns; database operations must bind canonical database identities.
21
+ - **Strict Path Containment:** All filesystem paths and database files must strictly reside within designated sandbox roots via `resolve_contained_path`, rejecting relative traversal, absolute escapes, and symlink redirects.
22
+ - **Offline Dry-Run Isolation:** When `dry_run=True`, tools are strictly prohibited from opening network sockets, performing DNS resolution, modifying files, or issuing database writes.
23
+
24
+ ---
25
+
26
+ ## 2. Comprehensive Inventory Matrix
27
+
28
+ The following table catalogs all 10 side-effecting tools, entry points, egress destinations, mutated entities, legacy mechanisms, and remediated granular scopes within Synapse-Hub.
29
+
30
+ | # | Tool Path | Boundary Category | Side-Effect Action | Egress Target / Mutated Entity | Legacy Authorization (Vulnerable) | Remediated Granular Scope |
31
+ |---|---|---|---|---|---|---|
32
+ | **1** | `tools/api_fuzzer.py` | Network Egress (HTTP) | Dispatches HTTP fuzz vectors (SQLi, XSS, headers, path traversal) | Target Base URL & API Endpoints | `bool(consent)`, `PENTEST_CONSENT_ACKNOWLEDGED`, `--confirm-pentest-scope` | `action="http:fuzz"`, `target=canonical_url`, `method=HTTP_METHOD`, `path_pattern=PATH`, `caller_session`, `nonce`, `expiry` |
33
+ | **2** | `tools/db_sandbox.py` | Database Mutation | `restore_snapshot` (file overwrite / table wipe / schema rollback) | Target SQLite / RDBMS file | `bool(consent)`, `SYNAPSE_FORCE_RESTORE`, `PENTEST_CONSENT_ACKNOWLEDGED` | `action="db:restore"`, `db_identity=canonical_path`, `caller_session`, `nonce`, `expiry` |
34
+ | **3** | `tools/db_sandbox.py` | Database Mutation | `audit_and_purge_pollution` (`DELETE FROM ...` query execution) | Target SQLite database | `bool(consent)`, `SYNAPSE_FORCE_PURGE`, `PENTEST_CONSENT_ACKNOWLEDGED` | `action="db:purge"`, `db_identity=canonical_path`, `caller_session`, `nonce`, `expiry` |
35
+ | **4** | `tools/db_sandbox.py` (`wait-ready`) | Network Socket | TCP port connect & HTTP GET readiness probe | `host:port`, URL endpoint | None (unauthenticated socket probe) | `action="net:probe"`, `target=host:port`, `caller_session`, `nonce`, `expiry` |
36
+ | **5** | `tools/reversible_sandbox.py` | Filesystem Mutation & Subprocess | `FILE_DELETE`, `DIR_DELETE`, undo shell command execution | Target file / directory / shell execution | None (direct execution of logged undo strings) | Path containment (`resolve_contained_path`), rejection of traversal / symlinks escaping `sandbox_root` |
37
+ | **6** | `tools/micro_mutator.py` | Filesystem Mutation & Subprocess | Mutates source code on disk, creates `.synapse_mutator_bak`, runs `test_cmd` | Target source files (`.py`, `.ts`, `.groovy`, `.js`) | None (direct disk write & subprocess execution) | `action="fs:mutate"`, `target=canonical_file_path`, `caller_session`, `nonce`, `expiry` |
38
+ | **7** | `tools/wcag_audit.py` | Network Egress (HTTP) | Fetches HTML DOM for accessibility compliance audit | Target web URL | None (`urllib.request.urlopen` direct call) | `action="http:wcag_scan"`, `target=canonical_url`, `caller_session`, `nonce`, `expiry` |
39
+ | **8** | `tools/jira_sync.py` | Network Egress (HTTP) | Creates, updates, and transitions Jira issues | Jira Server/Cloud REST API URL | Jira token in env vars (no execution boundary) | `action="jira:sync"`, `target=canonical_jira_url`, `caller_session`, `nonce`, `expiry` |
40
+ | **9** | `tools/tms_sync_bridge.py` | Network Egress (HTTP) | Synchronizes test cases & results to TestRail/Zephyr | TMS Server REST API URL | TMS token in env vars (no execution boundary) | `action="tms:sync"`, `target=canonical_tms_url`, `caller_session`, `nonce`, `expiry` |
41
+ | **10** | `tools/hub_publisher.py` | Network Egress (HTTP) & Git | Creates tags, releases, inspects CI, publishes NPM package | GitHub API & NPM Registry | GitHub/NPM tokens, CLI `-y` flag | `action="release:publish"`, `target=github_npm_registry`, `caller_session`, `nonce`, `expiry` |
42
+
43
+ ---
44
+
45
+ ## 3. Granular Authorization Architecture (`ConsentGrant`)
46
+
47
+ ### 3.1 Grant Schema
48
+ The foundational authorization model resides in `tools/pentest_scope_guard.py` as an immutable dataclass:
49
+
50
+ ```python
51
+ @dataclass(frozen=True)
52
+ class ConsentGrant:
53
+ action: str # e.g., "http:fuzz", "db:restore", "db:purge", "fs:undo"
54
+ target: str # Canonical target (URL, host:port, or directory)
55
+ caller_session: str # Caller identity or conversation/session UUID
56
+ nonce: str # Cryptographic single-use nonce (hex/uuid)
57
+ expiry: float # Unix epoch timestamp in UTC
58
+ method: Optional[str] = None # e.g., "GET", "POST", "PUT", "DELETE"
59
+ path_pattern: Optional[str] = None # e.g., "/api/v1/users/*"
60
+ db_identity: Optional[str] = None # Canonical path to database file
61
+ metadata: Dict[str, Any] = field(default_factory=dict)
62
+ ```
63
+
64
+ ### 3.2 Verification Protocol
65
+ When evaluating a `ConsentGrant`, `verify_granular_grant` applies strict multi-point validation:
66
+ 1. **Type & Structural Integrity:** The object must satisfy `is_consent_grant(...)`, validating structural field existence and non-empty values.
67
+ 2. **Action Matching:** `grant.action` must exactly match the requested operation (e.g., `"http:fuzz"` vs `"db:restore"`).
68
+ 3. **Target Binding:** Canonical target normalization must match the operational destination (exact match or path containment).
69
+ 4. **Temporal Validity:** Current UTC timestamp must be strictly less than `grant.expiry`.
70
+ 5. **Single-Use Replay Prevention:** `grant.nonce` is checked against an in-memory consumed-nonce registry (`_GLOBAL_CONSUMED_NONCES`). If the nonce was previously registered, execution is denied with a `PermissionError("Replay detected: nonce ... already consumed")`.
71
+ 6. **Method & Path Pattern Matching:** If the action represents HTTP communication, `grant.method` must match the outgoing HTTP verb, and `grant.path_pattern` must match the URL path (supporting glob patterns via `fnmatch`).
72
+ 7. **Database Identity Matching:** For database actions (`db:restore`, `db:purge`), `grant.db_identity` must match the canonicalized database filepath.
73
+
74
+ ---
75
+
76
+ ## 4. Path Containment Architecture (`resolve_contained_path`)
77
+
78
+ ### 4.1 Threat Model
79
+ Filesystem and database tooling frequently operate with path parameters supplied by configuration files, test scripts, CLI arguments, or AI agent prompts. Attack vectors include:
80
+ - **Relative Traversal:** Path strings utilizing `../` or `..\\` sequences to break out of temporary directories.
81
+ - **Absolute Path Escapes:** Providing absolute paths (e.g., `/etc/passwd`, `/data/prod.db`, or system directories).
82
+ - **Symlink Escapes:** Utilizing directory or file symlinks pointing to sensitive locations outside the designated sandbox root.
83
+
84
+ ### 4.2 Resolution Algorithm
85
+ `resolve_contained_path(sandbox_root, target_path)` enforces containment via canonical realpath resolution:
86
+
87
+ ```python
88
+ def resolve_contained_path(sandbox_root: str, target_path: str) -> str:
89
+ """Normalize and resolve target_path, ensuring it strictly resides within sandbox_root.
90
+
91
+ Rejects:
92
+ - Relative traversal ('..') escaping the root
93
+ - Symlinks pointing outside the sandbox root
94
+ - Absolute paths residing outside sandbox root
95
+ """
96
+ if not sandbox_root or not str(sandbox_root).strip():
97
+ raise PathContainmentError("Sandbox root cannot be empty.")
98
+ if not target_path or not str(target_path).strip():
99
+ raise PathContainmentError("Target path cannot be empty.")
100
+
101
+ canon_root = os.path.realpath(os.path.abspath(sandbox_root))
102
+
103
+ # Resolve absolute candidate relative to sandbox_root if relative
104
+ if os.path.isabs(target_path):
105
+ candidate = os.path.abspath(target_path)
106
+ else:
107
+ candidate = os.path.abspath(os.path.join(canon_root, target_path))
108
+
109
+ canon_target = os.path.realpath(candidate)
110
+
111
+ # Path containment check via os.path.commonpath
112
+ try:
113
+ common = os.path.commonpath([canon_root, canon_target])
114
+ except ValueError as exc:
115
+ raise PathContainmentError(f"Path containment check failed across distinct drive roots: {exc}")
116
+
117
+ if common != canon_root:
118
+ raise PathContainmentError(
119
+ f"Path containment violation: '{target_path}' resolves to '{canon_target}', "
120
+ f"which escapes designated sandbox root '{canon_root}'."
121
+ )
122
+
123
+ return canon_target
124
+ ```
125
+
126
+ ---
127
+
128
+ ## 5. Offline Dry-Run Isolation Semantics
129
+
130
+ In autonomous multi-agent environments, dry-run modes are frequently executed for planning, simulation, test discovery, and code review.
131
+
132
+ ### Invariants for `dry_run=True`:
133
+ 1. **Zero Socket Creation:** Direct TCP/UDP socket opening (`socket.socket`, `socket.create_connection`) is strictly prohibited.
134
+ 2. **Zero DNS Queries:** Remote hostname lookups via `socket.getaddrinfo` or `urllib.request` must not occur during dry-run instantiation or plan generation.
135
+ 3. **Zero Remote HTTP Requests:** Outgoing HTTP/HTTPS client requests are prohibited. Any mocked execution must return simulated offline payloads with simulated status code `0` or `200` without dispatching network packets.
136
+ 4. **Zero Filesystem Mutation:** Files on disk must not be created, edited, moved, or deleted. Temporary backup copies must not be written during dry-run evaluations.
137
+ 5. **Zero Database Mutation:** Neither table schema updates, snapshot file overwrites, nor `DELETE` / `DROP` queries may be executed against databases.
138
+
139
+ ---
140
+
141
+ ## 6. Tool-by-Tool Detailed Profiles
142
+
143
+ ### 6.1 `tools/api_fuzzer.py`
144
+ - **Boundary Category:** Network Egress (HTTP / REST APIs).
145
+ - **Entry Points:** `ApiFuzzer.__init__`, `ApiFuzzer.load_spec`, `ApiFuzzer.execute_request`, `main()`.
146
+ - **Side Effects:** Transmits adversarial HTTP mutation payloads (SQL injection, XSS vectors, oversized headers, boundary mutations) to target endpoints.
147
+ - **Legacy Defects:** Bypassed authorization checks if `consent=True` was passed as a boolean, if the unauthenticated environment variable `PENTEST_CONSENT_ACKNOWLEDGED=1` was present, or if `--confirm-pentest-scope` CLI flag was set. Dispatched DNS requests and remote spec fetches even when dry-run was desired.
148
+ - **Remediated State:**
149
+ - Instantiation and `load_spec` accept `dry_run=True`; bypasses network spec fetches and remote DNS lookups when offline.
150
+ - `execute_request` requires a valid `ConsentGrant`. Validates expiry, nonce single-use, canonical base URL, HTTP method, and endpoint path match (supporting fnmatch globbing).
151
+ - Dry-run execution generates simulated `is_fuzzed=True` records with zero network packet transmission.
152
+
153
+ ### 6.2 `tools/db_sandbox.py` (Snapshot Restore & Pollution Purge)
154
+ - **Boundary Category:** Database Mutation (SQLite / RDBMS).
155
+ - **Entry Points:** `DatabaseSandbox.restore_snapshot`, `DatabaseSandbox.audit_and_purge_pollution`, `main()`.
156
+ - **Side Effects:** Overwrites database file with baseline snapshot binary, drops tables, or issues `DELETE FROM <table> WHERE ...` statements to eliminate test junk.
157
+ - **Legacy Defects:** Accepted boolean `consent=True`, or shared environment variables `SYNAPSE_FORCE_RESTORE=1`, `SYNAPSE_FORCE_PURGE=1`, and `PENTEST_CONSENT_ACKNOWLEDGED=1`. Did not constrain `self.db_path` within a designated sandbox root, allowing traversal to arbitrary host databases.
158
+ - **Remediated State:**
159
+ - `DatabaseSandbox.__init__` requires `sandbox_root` and validates `self.db_path` using `resolve_contained_path`.
160
+ - `restore_snapshot` and `audit_and_purge_pollution` reject boolean flags and environment variables. Both operations strictly mandate a valid `ConsentGrant` binding `action="db:restore"` or `action="db:purge"` and matching `db_identity`.
161
+ - When `dry_run=True`, database mutation routines exit immediately with zero disk writes and zero database queries.
162
+
163
+ ### 6.3 `tools/db_sandbox.py` (`wait-ready` Socket Probe)
164
+ - **Boundary Category:** Network Socket Probing (TCP / HTTP).
165
+ - **Entry Points:** `DatabaseSandbox.wait_ready`, `_probe_port`, `_probe_http`.
166
+ - **Side Effects:** Connects to TCP ports and sends HTTP GET requests to evaluate database container or service readiness.
167
+ - **Remediated State:**
168
+ - Validates `action="net:probe"` and target host/port bounds via `PentestScopeGuard`.
169
+ - Dry-run mode skips live socket binding and returns simulated readiness status.
170
+
171
+ ### 6.4 `tools/reversible_sandbox.py`
172
+ - **Boundary Category:** Filesystem Mutation & Subprocess Execution.
173
+ - **Entry Points:** `ReversibleSandbox.rollback_all`, `ReversibleSandbox.record_change`.
174
+ - **Side Effects:** Parses logged undo commands (`FILE_DELETE: <path>`, `DIR_DELETE: <path>`, or arbitrary shell command strings) and executes deletions or rollback subprocesses.
175
+ - **Legacy Defects:** Arbitrary paths were passed directly to `os.remove()` and `shutil.rmtree()`; non-prefixed undo commands were passed to `subprocess.run()`. No validation prevented directory traversal outside the project directory.
176
+ - **Remediated State:**
177
+ - Enforces `sandbox_root` containment via `resolve_contained_path` for all `FILE_DELETE` and `DIR_DELETE` targets.
178
+ - Rejects traversal attempts (`..`), symlinks escaping root, and absolute paths outside the designated sandbox root.
179
+
180
+ ### 6.5 `tools/micro_mutator.py`
181
+ - **Boundary Category:** Filesystem Mutation & Subprocess Execution.
182
+ - **Entry Points:** `MicroMutator.evaluate_mutants_dynamically`, `evaluate_target`.
183
+ - **Side Effects:** Mutates source code AST on disk, creates temporary backup files (`.synapse_mutator_bak`), and executes automated test runners via subprocess.
184
+ - **Remediated State:**
185
+ - Validates target source files against project repository containment.
186
+ - Ensures clean teardown and restoration of backup files even on runner interruptions.
187
+ - Operates in static AST analysis mode by default to prevent unwanted disk modifications during static audits.
188
+
189
+ ### 6.6 `tools/wcag_audit.py`
190
+ - **Boundary Category:** Network Egress (HTTP / DOM Scraper).
191
+ - **Entry Points:** `WcagAuditor.audit_url`, `main()`.
192
+ - **Side Effects:** Dispatches HTTP GET requests via `urllib.request.urlopen` to retrieve remote HTML pages for accessibility analysis.
193
+ - **Remediated State:**
194
+ - Integrates target validation through `PentestScopeGuard.validate_target` to prevent SSRF against loopback addresses, link-local metadata (e.g., `169.254.169.254`), and unauthorized internal networks.
195
+ - Requires `action="http:wcag_scan"` grant for active external scans.
196
+
197
+ ### 6.7 `tools/jira_sync.py` & `tools/tms_sync_bridge.py`
198
+ - **Boundary Category:** Network Egress & Remote State Mutation (External SaaS APIs).
199
+ - **Entry Points:** `JiraSync.create_issue`, `TmsSyncBridge.push_results`.
200
+ - **Side Effects:** Submits automated defect tickets or synchronizes test execution runs to enterprise management platforms (Jira, TestRail, Zephyr).
201
+ - **Remediated State:**
202
+ - Requires explicit session grants (`action="jira:sync"`, `action="tms:sync"`) before dispatching mutating REST calls (`POST`, `PUT`, `DELETE`).
203
+ - Restricts remote destination URLs to corporate Jira/TMS allowlists.
204
+
205
+ ### 6.8 `tools/hub_publisher.py`
206
+ - **Boundary Category:** Network Egress, Remote Git Mutation & Package Release.
207
+ - **Entry Points:** `HubPublisher.publish_release`, `main()`.
208
+ - **Side Effects:** Pushes git tags to remote origin, triggers GitHub Release API endpoints, and publishes packages to public or internal NPM registries.
209
+ - **Remediated State:**
210
+ - Enforces strict CLI interactive confirmation (or explicit `--yes` with validated environment variables).
211
+ - Governed by Git Push Protocol and `action="release:publish"` grant binding.
212
+
213
+ ---
214
+
215
+ ## 7. Audit Trail, Nonce Management & Telemetry
216
+
217
+ 1. **Consumed Nonce Registry:** In-memory registry `_GLOBAL_CONSUMED_NONCES` prevents replay attacks during long-running agent workflows. A helper `clear_consumed_nonces()` is provided for test teardowns.
218
+ 2. **Audit Logging:** Every grant creation, grant verification failure, path containment violation, and authorization denial is recorded with structured security logs (`SECURITY: ...`, `PathContainmentError`, `PermissionError`).
219
+ 3. **Fast-Fail on Authorization Mismatch:** Failure to provide a valid grant fails closed immediately (raising `PermissionError` or returning structured error codes) without executing partial or exploratory side effects.
220
+
221
+ ---
222
+
223
+ ## 8. Compliance Checklist for Future Side-Effecting Tools
224
+
225
+ When adding new tools to Synapse-Hub that interact with external networks, filesystems, or databases, developers and AI agents must comply with the following checklist:
226
+
227
+ - [ ] **No Generic Boolean Consent:** Do not accept `consent: bool = True` or unauthenticated environment variables (`FORCE_*`, `PENTEST_*`) as an authorization bypass.
228
+ - [ ] **Enforce `ConsentGrant`:** Require a `ConsentGrant` object verifying `action`, `target`, `nonce`, and `expiry` via `verify_granular_grant`.
229
+ - [ ] **Path Containment:** Validate all input and output filesystem paths using `resolve_contained_path(sandbox_root, path)`.
230
+ - [ ] **Offline Dry-Run:** Implement `dry_run: bool = False`. Guarantee zero socket creation, zero DNS resolution, zero file writes, and zero database mutations when `dry_run=True`.
231
+ - [ ] **SSRF & Network Guard:** Route all HTTP/TCP destinations through `PentestScopeGuard.validate_target` to prevent loopback, link-local, and metadata service probing.
232
+ - [ ] **Idempotent Teardown:** Ensure any state modified during execution is recorded for rollback or cleaned up in an automated teardown block.
233
+ - [ ] **Inventory Update:** Add the new tool and its required granular scope to this inventory document.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@teevee98/synapse-hub",
3
- "version": "4.2.0",
3
+ "version": "4.2.1",
4
4
  "description": "Enterprise AI Agent Intelligence Hub & Autonomous Skill Network",
5
5
  "publishConfig": {
6
6
  "access": "public"
package/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "synapse-hub",
3
3
  "displayName": "Synapse Hub Enterprise QA",
4
- "version": "4.2.0",
4
+ "version": "4.2.1",
5
5
  "description": "Enterprise AI Agent Intelligence Hub & Autonomous Skill Network for Quality Engineering, Clean POM, and Automated Testing.",
6
6
  "author": {
7
7
  "name": "TeeVee98",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
3
  "name": "Synapse-Hub",
4
- "version": "4.2.0",
4
+ "version": "4.2.1",
5
5
  "description": "Unified Catalog of 53 Skills across 11 Domain Packages for Enterprise QA AI Agents.",
6
6
  "totalSkills": 53,
7
7
  "domains": {