synapse-hub 2.4.3 → 2.6.0

package/.agents/rules/skill-precedence.md

@@ -1,6 +1,6 @@
 ---
 trigger: always_on
-description: Skill Resolution Precedence and Anti-Collision Protocol enforcing Workspace-Local skills over external generic plugin skills.
+description: Skill Resolution Precedence, Inter-Skill Coordination, and Anti-Collision Protocol enforcing Workspace-Local skills over external generic plugin skills.
 ---
 
 # Skill Resolution Precedence & Anti-Collision Protocol
@@ -9,34 +9,34 @@ description: Skill Resolution Precedence and Anti-Collision Protocol enforcing W
 
 ---
 
-## 1. Non-Negotiable Precedence Order
+## 1. Non-Negotiable 3-Tier Precedence Order
+`[Tier 1: Project-Local Skills] (.agents/skills/*)` > `[Tier 2: Core Rules] (.agents/rules/*)` > `[Tier 3: External Plugins] (generic plugins)`.
+Whenever a Tier 1 local skill exists, the external plugin skill is **strictly suppressed**.
 
-When executing tasks within automated testing repositories, Agent must strictly apply the following resolution order:
+---
 
-```text
-[Tier 1: Project-Local Skills] (.agent/skills/*) 
-       v (Higher priority - Specialized & Context-Aware)
-[Tier 2: Core Project Rules] (.agents/rules/*)
-       v
-[Tier 3: External Plugin Skills] (antigravity-testing-kit, chrome-devtools-plugin)
-```
+## 2. External Plugin Suppression Rules (Tier 1 overrides Tier 3)
+- **POM & Test Authoring:** Use `clean-pom-crafter` / `lam-script-generator`. Suppress generic QA/test plugins. Flat Clean POM only; no raw XPaths in test scripts.
+- **Code Review:** Use `senior-code-review` (6 pillars against git diff). Suppress generic PR reviewers.
+- **Locator Healing:** Use `self-healing-locator` / `failure-autopsy-and-healing` (AOM diffing). Suppress generic locator healers.
+- **Flaky Test Triage:** Use `flaky-test-sentinel-and-quarantine` (episodic SQLite memory + JUnit parsing).
+- **Live Probing:** Use `playwright-live-interaction` (CDP idle 0 under 200ms). Suppress generic smart locators.
+- **Accessibility:** Use `wcag-audit-patterns` for WCAG 2.2 A/AA criteria; use Chrome DevTools MCP strictly for low-level node inspection.
 
 ---
 
-## 2. Specific Skill Mapping & Exclusion Matrix
-
-| Task Type | REQUIRED Skill (Tier 1) | EXCLUDED / SUPPRESSED Skill (Tier 3) | Reason |
-|---|---|---|---|
-| **Test Script & POM Generation** | `clean-pom-crafter`<br/>`lam-script-generator` | `QA Automation Engineer` | Enforces Flat Architecture, zero XPaths in scripts, dynamic `uniqueCode`, and 2-phase search. Generic plugin templates violate Clean POM standards. |
-| **Locator Healing & DOM Diffing** | `self-healing-locator`<br/>`failure-autopsy-and-healing` | `Locator Healer Agent` | Uses token-efficient AOM diffing (Role > Label > TestId) and reads local JUnit XML/Screenshots. |
-| **Flaky Test Triage & Root Cause** | `failure-autopsy-and-healing` | `Flaky Test Analyzer` | Triage occurs via 0-token JUnit XML parsing, `Screenshots/FAILED_*.png` autopsy, and SQLite cosine cache (`memory_cache.db`). |
-| **Live Web & Locator Probing** | `playwright-live-interaction` | `Smart Locator Agent` | Direct CDP network idle 0, dynamic overlay bypass, and in-browser helper integration. |
-| **Code Refactoring & Tech Debt** | `code-refactoring-refactor-clean` | *(Consolidated)* | Single unified skill covering SOLID refactoring, code smells, and technical debt remediation. |
-| **Accessibility (A11y) Testing** | `wcag-audit-patterns`<br/>*(Guideline)* | `a11y-debugging`<br/>*(Tooling Only)* | `wcag-audit-patterns` governs WCAG 2.2 rules; `a11y-debugging` is used solely for low-level Chrome DevTools inspection. |
+## 3. Internal Inter-Skill Coordination & Boundaries
+- **Code Authoring:** `lean-code-ladder` decides *what* to build (7-rung ladder); `surgical-coding-principles` restricts *where* to touch (surgical git diff).
+- **Technical Debt:** `technical-debt-harvester` tracks `shortcut:` markers; `code-refactoring-refactor-clean` executes refactoring.
+- **Quality Review:** `senior-code-review` audits source diffs; `review-spec` audits requirements/stories (0-context stress test).
+- **System Audit:** `tools/analyze_project.py` gathers facts (AST, env, gates); `repo-quality-audit` prioritizes "Fix #1 first".
+- **API Testing:** `api-spec-to-e2e-matrix` compiles test matrices; `api-network-mocking-interception` stubs routes and chaos faults.
+- **Failure Analysis:** `self-healing-locator` heals individual locators; `failure-autopsy-and-healing` triages suite-wide crashes.
+- **DoD Gatekeeper:** `verification-before-completion` checks fresh command evidence; `antigravity-test-sentinel` enforces all 10 gates.
 
 ---
 
-## 3. Strict Prohibitions
-
-1. **Never use generic test generation:** Do not generate boilerplate Selenium/Cucumber tests from external plugins that use `findTestObject` or Object Repository folders.
-2. **Never dump raw HTML for locator healing:** Always extract compact AOM subtrees (< 500 tokens).
+## 4. Strict Prohibitions
+1. **Zero Generic Boilerplate:** Never generate legacy Selenium, Cucumber, or `findTestObject` code.
+2. **Zero Raw HTML Dumps:** Extract compact AOM subtrees (< 500 tokens); never dump raw HTML trees.
+3. **Zero Unverified Assertions:** Never complete tasks without running fresh verification via `tools/verify_all.py`.

package/.agents/rules/systematic-debugging.md

@@ -31,7 +31,7 @@ This rule governs all AI Agents operating on the repository. It mandates strict
      ```bash
      python3 tools/verify_all.py
      ```
-   - All 9 Gates must return `PASS`. If any gate fails, the task is NOT complete.
+   - All 10 Gates must return `PASS`. If any gate fails, the task is NOT complete.
 2. **Targeted Re-Test:**
    - After modifying Page Classes, check impacted Test Cases with:
      ```bash
@@ -46,32 +46,15 @@ This rule governs all AI Agents operating on the repository. It mandates strict
 
 ## 3. Situational Tool Dispatch Matrix & Zero-Command Autonomy
 
-> 🚀 **Zero-Command Autonomous Invariant (Zero Manual Commands):**  
-> The user **NEVER** needs to remember syntax or manually type tool commands (`agent-qa setup`, `agent-qa analyze`, `verify_all.py`...).  
-> The AI Agent **MUST AUTONOMOUSLY recognize context and trigger** the corresponding tools below on-demand whenever the situation arises.  
->  
-> 🎯 **On-Demand Activation Principle (Situation-Specific — Never Run Blindly):**  
-> Tools assigned to AI and Subagents are **situational weapons**, **NEVER executed all at once**. Agents draw the specific tool from the arsenal if and only if a concrete need arises (e.g.: failing test triggers `auto_heal`, new project triggers `setup_project`, API breaking change triggers `api_drift_sentinel`).
-
-| Context / Trigger | Mandatory Tool | Specific Objective |
-| :--- | :--- | :--- |
-| **New project / Missing `PROJECT_AI_GUIDE.md` / Fresh clone** | `python3 tools/setup_project.py [target]` | 100% Autonomous: Detects framework (Playwright/Katalon/Pytest), generates `PROJECT_AI_GUIDE.md`, installs `pre-push` hook, extracts `repo_map.txt`, runs initial audit. |
-| **User requests: "analyze project" / "re-analyze" / "project audit"** | `python3 tools/analyze_project.py [target]` | Execute comprehensive 5-in-1 health audit, sync repo_map, infer_linter, data_flow, verify_all & generate PROJECT_HEALTH_REPORT.md.<br/>**Post-Action:** Stage, commit & push updated project files (`PROJECT_HEALTH_REPORT.md`, `repo_map.txt`) to git. |
-| **Starting task / Querying Page Class methods** | `tools/repo_map.txt`<br/>*(run `python3 tools/repo_map.py` if classes changed)* | Read compressed 500-token map for signatures; avoid reading 4,000-line files. |
-| **Dispatching Browser Actions (Live/CDP)** | `python3 tools/safety_firewall.py --dry-run` | Mandatory Pre-execution Hook: Block irreversible/destructive operations before browser dispatch. |
-| **Creating or updating Test Scripts** | `python3 tools/infer_linter.py` | Run AST scan for Fake-Pass (0 asserts) and empty catch blocks. |
-| **New/Modified Test Case Quality** | `python3 tools/micro_mutator.py --min-score 80` | AST Mutation Testing: Reject test suites with mutation score < 80%. |
-| **Before Git Commit or Completing Task** | `python3 tools/verify_all.py` | Validate all 9 Quality Gates DoD. |
-| **After modifying Page Classes** | `python3 tools/test_impact.py --git-diff` | Scope impacted test cases; avoid re-running entire test suites. |
-| **When Test FAILS in CLI/KRE** | `python3 tools/pinpoint_failure.py` | Parse JUnit XML to identify exact failing line and exception in 0.1s. |
-| **When CLI / Gradle logs are verbose** | `python3 tools/distill_log.py <log>` | Filter 95% noise; preserve only actionable stacktraces and pointers. |
-| **Handling UI exceptions (Overlay, Stale)** | `python3 tools/cache_resolver.py query "<error>"` | Lookup 0-token solution from local SQLite memory cache before improvising. |
-| **Pre-Push / Suite Acceptance** | `python3 tools/trace_data_flow.py` | Run Taint Analysis to verify no orphan database junk remains uncleaned. |
-| **Canary Self-Healing Audit** | `python3 tools/agent_canary.py --run` | Inject 8 failure vectors to benchmark MTTR and autonomous recovery rate. |
-| **Testing GIS Canvas / Chart without DOM** | `python3 tools/visual_diff_canvas.py` | Compare pixel / SSIM to detect visual rendering regression. |
-| **Pulling code / New clone** | `python3 tools/cache_resolver.py init` | Automatically sync Central Agent Memory (`~/.agent_memory/global_cache.db`). |
-| **Before authoring test for Page/Flow** | `python3 tools/cache_resolver.py get-lessons --context "<page>"` | Query top 2 episodic lessons learned to avoid repeating past failure patterns. |
-| **After healing a bug / failure** | `python3 tools/cache_resolver.py record-lesson` | Record a concise 2-line lesson into SQLite memory for cross-session reflexion. |
+> 🚀 **Zero-Command Autonomous Invariant:** The user **NEVER** needs to manually type tool commands. The AI Agent **MUST AUTONOMOUSLY recognize context and trigger** the corresponding tools on-demand. Never run tools blindly; invoke only when the concrete situation arises.
+
+- **Setup & Audit:** New project -> `tools/setup_project.py`; Project audit -> `tools/analyze_project.py`; Code review -> `tools/senior_code_review.py`; Debt scan -> `tools/debt_harvester.py`.
+- **Quality Gates & DoD:** Pre-commit/Handoff -> `tools/verify_all.py` (10 Gates DoD); Script lint -> `tools/infer_linter.py`; Mutation testing -> `tools/micro_mutator.py --min-score 80`.
+- **Failure Autopsy & Healing:** Test failure -> `tools/pinpoint_failure.py` (parse JUnit XML in 0.1s); Iterative repair -> `tools/auto_heal_reflexion.py`; Reversible rollback -> `tools/reversible_sandbox.py`.
+- **Context & Safety:** Verbose logs -> `tools/distill_log.py`; Destructive browser actions -> `tools/safety_firewall.py`; Method signatures -> `tools/repo_map.txt`.
+- **Memory & Reflexion:** UI exceptions -> `tools/cache_resolver.py query "<error>"`; Query/Save proven patterns -> `tools/skill_vault.py`.
+
+*(For the complete CLI parameters and full tools catalog, refer to [tools/TOOLS_RUNBOOK.md](file://tools/TOOLS_RUNBOOK.md)).*
 
 ---
 

package/.agents/skills/lean-code-ladder/SKILL.md

@@ -9,7 +9,18 @@ Specialized skill for minimizing newly written code in test automation projects:
 
 ---
 
-## 1. The 7-Rung Ladder
+## 1. The 7-Rung Ladder & Intensity Levels
+
+### Intensity Levels
+
+| Level | Behavior |
+|:---:|---|
+| **lite** | Build what was asked. Name the smaller/lazier option in one line and let the user pick. |
+| **full** | The standard 7-rung ladder rules below. (Default) |
+| **ultra** | Deletion before addition: question the request and push back on any part the business need does not strictly justify. |
+| **off** | Deactivate lean constraints; standard code synthesis. |
+
+### The 7-Rung Ladder
 
 Before writing any new code, descend the ladder and take the **first rung that fully works**:
 

package/.agents/skills/lean-impact-scoreboard/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lean-impact-scoreboard
+description: "Display the measured impact scoreboard (code reduction %, token optimization %, cost reduction %, test rigor) from lean engineering benchmarks."
+category: architecture_and_analysis
+version: "1.0.0"
+---
+
+# Lean Impact Scoreboard — Verified Efficiency & Token Benchmarks
+
+Displays empirical metrics and benchmarks demonstrating the impact of Lean Engineering (The 7-Rung Ladder, Clean POM, and Verification-First).
+
+---
+
+## 1. Benchmark Overview
+
+Based on extensive agentic benchmarks (39 real-world tasks across backend, frontend, security, and test suites):
+
+```text
+================================================================================
+Metric                           Baseline (No Skill)      Lean Mode       Delta
+================================================================================
+Lines of Code Generated          100%                    47%            -53% 📉
+Output Tokens Consumed           100%                    55%            -45% 📉
+API Cost                         100%                    74%            -26% 📉
+Agent Execution Time             100%                    59%            -41% ⚡
+Risky Logic Shipped with Tests   68%                     98%            +30% 🛡️
+Bug Detection Rate (Mutants)     46%                     66%            +20% 🎯
+================================================================================
+```
+
+---
+
+## 2. Key Insights
+
+1. **Less Code, Zero Loss of Safety:**
+   The goal is never code golfing. Code is concise because unnecessary abstractions, speculative wrappers, and redundant libraries are eliminated. Validation, trust boundaries, error handling, and accessibility are never compromised.
+2. **Empirical Verification Over Guesswork:**
+   98% of all risky logic (branches, parsers, auth, financial paths) ships with an automated unit assertion, compared to only 68% in standard unconstrained AI runs.
+3. **Real Per-Repo Metrics:**
+   Never hallucinate synthetic per-repo savings figures. For repository-specific health and debt measurements:
+   - Run `agent-qa debt` to review tracked shortcut debt.
+   - Run `python3 tools/analyze_project.py` to inspect AST maps and Quality Gate adherence.
+
+---
+
+## 3. Attribution
+
+Adapted from **ponytail-gain** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-calibrated for Enterprise QA and Synapse Hub benchmarks.

package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md

@@ -0,0 +1,20 @@
+# Sample Lean Impact Scoreboard
+
+Representative scoreboard displayed by `/synapse-gain`:
+
+```text
+================================================================================
+Metric                           Baseline (No Skill)      Lean Mode       Delta
+================================================================================
+Lines of Code Generated          100%                    47%            -53% 📉
+Output Tokens Consumed           100%                    55%            -45% 📉
+API Cost                         100%                    74%            -26% 📉
+Agent Execution Time             100%                    59%            -41% ⚡
+Risky Logic Shipped with Tests   68%                     98%            +30% 🛡️
+Bug Detection Rate (Mutants)     46%                     66%            +20% 🎯
+================================================================================
+```
+
+### Explanatory Context
+- **Why less code?** Reuses existing codebase helpers, standard libraries, and native platform widgets instead of reinventing wheels.
+- **Why more tests?** Enforces the completeness invariant: any non-trivial branch, loop, parser, or security logic must ship with a small test proving edge-case correctness.

package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md

@@ -0,0 +1,15 @@
+# Sample Lean Impact Scoreboard
+
+## Example Display
+```text
+==============================================================================
+                    SYNAPSE LEAN IMPACT SCOREBOARD
+==============================================================================
+  Target Repository       : EnterprisePaymentGateway
+  Lines of Code Removed   : -4,820 lines (-34.2%)
+  Token Consumption Drop  : -58.4%
+  Estimated Cloud Cost    : -\$1,420 / mo
+  Quality Gate Status     : 100% PASS (9/9 Gates DoD)
+  Mutation Score          : 91.4% (Threshold: >= 80%)
+==============================================================================
+```

package/.agents/skills/repo-quality-audit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: repo-quality-audit
+description: "Quality audit of a whole codebase: bugs, security risks, concurrency and scale bottlenecks, missing test coverage, and code bloat. Ranks findings with 'Fix this first' priority."
+category: architecture_and_analysis
+version: "1.0.0"
+---
+
+# Repo Quality Audit — Comprehensive Repository Health & Risk Audit
+
+Audit an entire repository like the senior engineer who just inherited it and will be paged when it breaks.
+Prioritize: **Correctness -> Safety -> Scale -> Tests -> Speed -> Lean**.
+Always rank issues and provide a clear **"Fix this first"** verdict.
+
+---
+
+## 1. Mapping the Codebase First
+
+Before diagnosing defects:
+1. **Entry Points & Architecture:** Inspect entry points (CLI commands, route handlers, test runners, background workers) and dependency manifests (`package.json`, `pyproject.toml`, `pom.xml`, `build.gradle`).
+2. **Expected Load:** Determine whether the system is a local utility, a parallel CI suite, or a high-throughput microservice.
+3. **Data Flow Tracing:** Trace critical business flows end-to-end:
+   - External inputs and request payloads
+   - Authentication & authorization checks
+   - Database mutations and state persistence
+   - Teardown and cleanup lifecycles
+
+---
+
+## 2. Six Audit Dimensions
+
+| Dimension | Inspection Focus | Red Flags |
+|---|---|---|
+| **1. Bugs & Logic** | Edge cases, return type mismatches, error handling | Swallowed exceptions, null dereferences, broken callers |
+| **2. Security & Data** | Trust boundaries, authentication, secrets | Hardcoded tokens, SQLi/RCE risks, missing input sanitization |
+| **3. Concurrency & Scale** | Resource contention, memory lifecycle | Race conditions, static sleeps, unbounded caches, unclosed connections |
+| **4. Test Deficit** | Untested business-critical logic | Complex branches or parsers with zero test assertions |
+| **5. Performance** | Hot paths, loop overhead | Unindexed queries, redundant network calls, $O(n^2)$ iterations |
+| **6. Bloat & Dead Code** | Code that should not exist | Unused dependencies, duplicate helper functions, single-impl interfaces |
+
+---
+
+## 3. Reporting Structure
+
+1. **Overview & Assumptions:**
+   - What this codebase does
+   - The operational load assumed
+2. **Ranked Findings (Max 20, ordered by severity):**
+   - **Must fix (Blockers):** Bugs causing data loss, security CVEs, unhandled crashes.
+   - **Should fix (Reliability):** Concurrency races, missing regression tests, flaky waits.
+   - **Nice to have (Hygiene):** Dead code removal, dependency pruning, code deduplication.
+3. **Verdict & Lean Metric:**
+   - **Verdict:** "Fix #1 first: [Summary of top priority issue]"
+   - **Lean Savings Potential:** Potential reduction in lines of code (`-N lines`) and unused dependencies (`-M dependencies`).
+   - **Not Checked:** Explicitly state any submodules or third-party assets omitted.
+
+---
+
+## 4. Complementary Hub Tools
+
+- `python3 tools/analyze_project.py` — 5-in-1 automated health audit and AST repo map.
+- `python3 tools/verify_all.py` — 9 Quality Gates DoD gatekeeper.
+- `python3 tools/debt_harvester.py` — Scan repository for unaddressed shortcut debt.
+
+---
+
+## 5. Attribution
+
+Adapted from **ponytail-audit** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-architected for Enterprise QA and Synapse Hub Standards.

package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md

@@ -0,0 +1,15 @@
+# Sample Repo Quality Audit Walkthrough
+
+## Overview
+This walkthrough demonstrates a repo-wide quality audit identifying high-impact risks with "Fix this first" prioritization.
+
+## Example Command
+```bash
+agent-qa audit . --output REPO_QUALITY_AUDIT.md
+```
+
+## Sample Output Findings
+1. **Critical:** In-memory queue without persistent backoff under concurrent load (`WorkerPool.groovy:142`).
+   - *Fix:* Introduce Redis-backed queue or bounded worker pool.
+2. **Medium:** Unbounded mock API responses causing potential memory bloat (`MockServer.groovy:89`).
+   - *Fix:* Enforce pagination or bounded payload limits.

package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md

@@ -0,0 +1,33 @@
+# Sample Repository Quality Audit
+
+Representative full-repo quality audit report:
+
+```markdown
+# Repository Quality Audit Report
+
+- **Target Repository:** `warehouse-inventory-api`
+- **Assumed Load:** 50 concurrent warehouse scanners + batch office imports (up to 5,000 items).
+
+### Findings (Ranked Priority)
+
+#### 1. [Must Fix] Office Batch Import Fails on Row 1,200 (`src/importers/csv.py:45`)
+- **What this is:** In-memory batch processor loading entire CSV into a single transaction.
+- **Problem:** When batch exceeds 1,000 items, database pool exhausts connection limits and drops connection silently.
+- **Fix:** Chunk processing into 250-row windowed transactions.
+- **If we skip it:** Nightly stock sync fails for all regional warehouses.
+
+#### 2. [Should Fix] Risky Discount Logic Has No Tests (`src/services/pricing.py:112`)
+- **What this is:** Tiered pricing rule engine based on customer loyalty grade.
+- **Problem:** Complex ternary branching calculates negative discounts if grade is undefined. Zero unit tests cover this branch.
+- **Fix:** Add boundary unit tests in `tests/test_pricing.py` asserting non-negative pricing.
+- **If we skip it:** Special promotions risk leaking negative prices to checkouts.
+
+#### 3. [Nice to Have] Dead Legacy XML Exporter (`src/exporters/legacy_xml.py`)
+- **What this is:** Deprecated XML export helper replaced by REST API 6 months ago.
+- **Fix:** Delete the 120-line unused module.
+- **If we skip it:** Maintenance burden and confusion for new team members.
+
+### Verdict
+Fix #1 first: Chunk batch imports into 250-row windowed transactions.
+Lean Potential: -120 dead lines, -1 unused XML library.
+```

package/.agents/skills/senior-code-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: senior-code-review
+description: "Quality review of a code change: verify logic correctness, security boundaries, real concurrency/load, missing test coverage, execution speed, and eliminate bloat. Reads connected callers and data flows, not just the diff."
+category: architecture_and_analysis
+version: "1.0.0"
+---
+
+# Senior Code Review — Enterprise Quality & Lean Diff Review
+
+Review code changes like the senior engineer who will be paged at 2 AM when it breaks.
+Order of importance: **Correctness -> Safety -> Scale -> Tests -> Speed -> Lean**.
+Lean still matters: every extra line must be read, tested, and fixed later.
+
+---
+
+## 1. Understand First
+
+- **Target Scoping:** Review what the user requests: uncommitted or staged changes, a branch, a PR link, or specific files. If unspecified: uncommitted changes (or last commit if clean).
+- **Read Beyond the Diff:** Read the diff, then read the code it touches:
+  - Callers of every changed function or Page Class method.
+  - Functions and services called by the diff.
+  - Associated unit/E2E tests and fixtures.
+- **Trace the Real Flow:** Where does user input arrive? What is validated? Where is state persisted? What is emitted?
+- **Expected Scale:** Identify the expected operational load (single script execution vs concurrent CI runners or thousands of users). Judge scale against that.
+
+---
+
+## 2. Six Core Review Pillars
+
+### 1. Bug & Edge Cases
+- Wrong calculation, crash, or unhandled edge cases (empty collections, zero values, timezone drift, string encoding).
+- Callers broken by changed method signatures or altered return types.
+- A bug fixed in one caller while the shared function/keyword remains broken for others.
+
+### 2. Risk & Security
+- Injection vulnerabilities (SQL, Shell, Command, Path traversal).
+- Hardcoded secrets, plain tokens, or private keys.
+- Missing input validation at trust boundaries.
+- Data loss risks: swallowed errors, unhandled promise rejections, missing DB transactions.
+
+### 3. Scale & Concurrency
+- Race conditions (check-then-act without locking).
+- Memory or cache leaks (unbounded collections that only grow).
+- $O(n^2)$ iterations or N+1 queries on variable-sized data.
+- Static delays (`Thread.sleep`, `time.sleep`) that block event loops or fail under variable network latency.
+
+### 4. Missing Tests
+- New non-trivial logic (branch, loop, parser, auth check, payment/money path) lacking a test that fails when broken.
+- Every bug fix must include a regression test proving the fix.
+
+### 5. Speed & Latency
+- Bottlenecks in hot paths and repeated iterations.
+- Unnecessary synchronous I/O or redundant API re-fetching.
+
+### 6. Lean & Anti-Bloat
+- **Delete:** Dead code, commented-out code, unused options, speculative configuration.
+- **Reuse:** Leverage existing Page Classes, BasePage helpers, or utility functions.
+- **Stdlib / Native:** Use platform features instead of adding external dependencies.
+- **YAGNI:** Remove single-use abstractions, single-impl interfaces, and passthrough wrappers.
+
+---
+
+## 3. Concrete Reporting Format
+
+Every finding **must** have a concrete, reproducible failure scenario:
+
+```markdown
+#### [Severity: Must fix | Should fix | Nice to have] <Finding Title> (`<file>:<line>`)
+- **What this is:** <One concise sentence describing the touched code>
+- **Problem:** <Specific input or scenario that leads to the defect or failure>
+- **Fix:** <Smallest complete diff or code change to resolve the issue>
+- **If we skip it:** <What goes wrong in production or CI pipeline>
+```
+
+---
+
+## 4. Automation CLI
+
+Run the automated senior review tool on your current working tree:
+```bash
+python3 tools/senior_code_review.py            # Review uncommitted changes
+python3 tools/senior_code_review.py --staged   # Review staged git changes
+python3 tools/senior_code_review.py --branch main  # Compare against main branch
+```
+
+---
+
+## 5. Attribution
+
+Adapted from **ponytail-review** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-architected for Enterprise QA, Clean POM, and Synapse Hub Quality Gates.

package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md

@@ -0,0 +1,29 @@
+# Sample Senior Code Review Walkthrough
+
+Below is a representative senior code review performed on an API and test diff.
+
+```markdown
+# Senior Developer Quality & Lean Code Review
+
+- **Files Changed:** `3`
+- **Findings:** `2` (1 Must fix, 1 Should fix, 0 Nice to have)
+
+### 🚨 Must Fix (Blockers)
+
+#### 1. Swallowed Database Exception (`src/services/billing.py:84`)
+- **What this is:** Try-catch block around payment transaction commit.
+- **Problem:** When the gateway returns a network error, the exception is caught with `pass`, silently failing the invoice without alerting the user or reverting the database transaction.
+- **Fix:** Rethrow `PaymentGatewayException` and rollback the active DB transaction.
+- **If we skip it:** Invoices will appear as paid in UI while payments actually failed.
+
+### ⚠️ Should Fix (Reliability & Scale)
+
+#### 2. Static Sleep in Async Test (`tests/test_billing.py:32`)
+- **What this is:** `time.sleep(3)` placed after dispatching webhook.
+- **Problem:** Static wait causes test flakiness on slower CI runners and wastes 3 seconds on fast local runs.
+- **Fix:** Replace with `await waitForCondition(isWebhookReceived, timeout=5000)`.
+- **If we skip it:** CI pipeline will intermittently fail on high queue load.
+
+### Verdict
+❌ **Action Required:** Resolve 1 blocker before merging.
+```

package/.agents/skills/technical-debt-harvester/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: technical-debt-harvester
+description: "Harvest shortcut: comments into a tracked debt ledger so deliberate compromises do not rot into forgotten tech debt."
+category: architecture_and_analysis
+version: "1.0.0"
+---
+
+# Technical Debt Harvester — Pragmatic Shortcut & Deferral Tracker
+
+Harvest deliberate shortcut comments (`shortcut: <limit>, <when to upgrade>`) across the entire repository into a structured Markdown ledger so pragmatic compromises do not silently rot into permanent defects.
+
+---
+
+## 1. The Shortcut Comment Standard
+
+When writing lean code or taking a pragmatic shortcut under time or scope constraints, leave an inline comment specifying the **ceiling (limit)** and the **upgrade trigger**:
+
+```python
+# Format:
+# shortcut: <the limit>, <when to upgrade>
+
+# Examples:
+# shortcut: max 100 items in memory, migrate to Redis if active sessions exceed 1,000
+# shortcut: SQLite database, switch to PostgreSQL when concurrent writers > 5
+```
+
+Any shortcut comment that omits an upgrade trigger is classified as `no-trigger` and flagged for review.
+
+---
+
+## 2. Supported Comment Syntaxes
+
+The harvester automatically detects markers across all common language comment styles:
+- `# shortcut:` (Python, Bash, Ruby, YAML)
+- `// shortcut:` (TypeScript, JavaScript, Java, Groovy, C++, Go, Rust, C#)
+- `/* shortcut: ... */` (CSS, Multi-line blocks)
+- `-- shortcut:` (SQL, Lua)
+- `<!-- shortcut: ... -->` (HTML, XML, Markdown)
+
+*(Also backwards compatible with older `ponytail:` comments).*
+
+---
+
+## 3. Automation CLI
+
+```bash
+# Scan working directory and display ledger
+python3 tools/debt_harvester.py
+
+# Save output to Markdown file
+python3 tools/debt_harvester.py --output DEBT_LEDGER.md
+
+# Output in JSON format for CI tooling
+python3 tools/debt_harvester.py --json
+
+# Scan with custom keyword
+python3 tools/debt_harvester.py --keyword "DEBT:"
+```
+
+Or via the unified CLI:
+```bash
+agent-qa debt
+agent-qa debt --output DEBT_LEDGER.md
+```
+
+---
+
+## 4. Attribution
+
+Adapted from **ponytail-debt** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. Re-architected with native Python tooling for Synapse Hub.

package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md

@@ -0,0 +1,25 @@
+# Sample Technical Debt Ledger
+
+Representative output from `agent-qa debt`:
+
+```markdown
+# Technical Debt & Shortcut Ledger
+
+> **Ledger Policy:** Deliberate shortcuts prevent over-engineering. Track limits and upgrade triggers so they never rot silently into permanent defects.
+
+- **Repository:** `order-service`
+- **Total Shortcuts:** `3`
+- **Missing Upgrade Triggers:** `1` ⚠️ *(Action Required)*
+
+---
+
+| Location | Description | Ceiling (Limit) | Upgrade Trigger | Status |
+| :--- | :--- | :--- | :--- | :--- |
+| `src/cache.py:24` | In-memory Python dictionary cache | 1,000 active sessions | Migrate to Redis when worker count > 2 | ✅ Tracked |
+| `src/auth.py:89` | Synchronous token verification | Max 50 req/sec | Switch to async JWKS cache under high load | ✅ Tracked |
+| `src/pdf.py:14` | Hardcoded paper margin 10px | Not specified | None | ⚠️ `no-trigger` |
+
+### Recommended Action
+1. Review the `1` shortcut tagged `no-trigger` above and define concrete upgrade conditions.
+2. Run `agent-qa debt` in CI to monitor debt accumulation.
+```

package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md

@@ -0,0 +1,20 @@
+# Sample Technical Debt Ledger
+
+## Example Output
+```markdown
+# Technical Debt & Shortcut Ledger
+
+> **Ledger Policy:** Deliberate shortcuts prevent over-engineering. Track limits and upgrade triggers so they never rot silently into permanent defects.
+
+- **Repository:** `OrderService`
+- **Total Shortcuts:** `2`
+- **Missing Upgrade Triggers:** `0` ✅ *(All tracked)*
+
+---
+
+### Tracked Shortcuts
+1. `src/services/OrderProcessor.groovy:45`
+   - *Shortcut:* In-memory map cache
+   - *Ceiling:* 10,000 active orders
+   - *Upgrade Trigger:* Migrate to Redis when daily active orders > 10,000
+```

package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md

@@ -0,0 +1,49 @@
+# Context Engineering & Token Optimization Guide (Full Architecture)
+
+*(Synthesized from `muratcankoylan/Agent-Skills-for-Context-Engineering`, `alexgreensh/token-optimizer`, and `obra/superpowers`)*
+
+---
+
+## 1. Pillar 1: Observation Masking
+Raw tool outputs (CLI execution logs, Gradle builds, browser console traces) contain 90% repetitive noise and low-signal tokens.
+- **Log Truncation & Summarization:** Never dump thousands of lines into the active conversation. Extract only: failing line number, exception name, test case identifier (`TC-xxx`), and status.
+- **Pointer Masking:** Use structured references pointing to files on disk: `[Full raw log saved to file://<path>; 2,400 verbose lines omitted]`.
+
+---
+
+## 2. Pillar 2: Progressive Disclosure
+Never load large codebases or giant classes (over 500 lines) into context at once. Load information in 3 progressive tiers:
+- **Tier 1:** High-Level Index & Repo Map (< 150 lines) via `tools/repo_map.txt`.
+- **Tier 2:** Graph Semantic Scoping via `graphify explain` or `test_impact.py`.
+- **Tier 3:** Targeted Micro-Read (20-50 lines using `StartLine`/`EndLine`).
+
+---
+
+## 3. Pillar 3: KV-Cache Friendly Ordering
+LLM inference engines cache Key-Value (KV) attention states for identical prompt prefixes.
+- **Static Prefix First:** Keep instructions, rules, and tool schemas immutable at the top.
+- **Append-Only Dynamic State:** Only append new test results and tool observations at the bottom.
+- **Predictable Format:** Use identical pre-flight status badges on every turn to maximize cache hits (> 85%).
+
+---
+
+## 4. Pillar 4: Scoped Context & Compaction Anchoring
+- **Compaction State Anchoring:** Critical state must be persisted to disk in `PROJECT_STATE.md`. When compaction fires, re-anchor immediately from disk with zero memory loss.
+- **Workspace Isolation (`Workspace: 'share'`):** Subagents use isolated worktrees to prevent dirty tree collisions.
+- **Zero Context Contagion:** Subagents return distilled 3-5 line summaries; stdout remains in subagent sandbox.
+- **Data Partitioning:** Subagents append agent IDs to test data (`uniqueCode = "AUTO_" + time + "_SUB" + id`).
+
+---
+
+## 5. Pillar 5: Semantic Context Distillation (Pure Signal, Zero Noise)
+All sensory inputs must pass through deterministic filters:
+- **CLI Logs (`tools/distill_log.py`):** Truncate 95% of verbose lines.
+- **DOM Purifier (`qa.getCompactAOM`):** Strictly forbidden to send raw HTML. Use compact AOM (< 500 tokens).
+- **Universal IR (`tools/universal_ir.py`):** Author clean universal IR before emitting framework-specific code.
+
+---
+
+## 6. Pillar 6: Elephant-Goldfish Memory Model
+- **The Elephant (Stateful Orchestrator):** Narrows problem boundaries, gathers intent, drafts specs in `docs/specs/*.md`, maintains `PROJECT_STATE.md`. Never writes tests during design phase.
+- **The Goldfish (Stateless Subagent Swarm):** Fresh subagent with ZERO conversation history; evaluates solely cold artifacts on disk via `tools/goldfish_review.py`.
+- **Air-Gap Data Contract:** All inter-stage data exchanges pass via disk files (JSON/JUnit XML), never raw prompt inheritance.