synapse-hub 2.4.3 → 2.5.0

package/.agents/agents/orchestrator.md

@@ -9,6 +9,7 @@ skills:
   - github-actions-templates
   - meta-prompt-crafter
   - token-and-context-optimizer
+  - repo-quality-audit
 tools:
   - tools/setup_project.py
   - tools/analyze_project.py

package/.agents/agents/pom-crafter.md

@@ -10,6 +10,7 @@ skills:
   - db-state-verifier-and-seeder
   - surgical-coding-principles
   - lean-code-ladder
+  - technical-debt-harvester
   - gherkin-to-suite
   - api-network-mocking-interception
   - rbt-manual-testing

package/.agents/agents/quality-gatekeeper.md

@@ -10,6 +10,8 @@ skills:
   - security-dast-sentinel
   - verification-before-completion
   - skillspector-security-guard
+  - senior-code-review
+  - technical-debt-harvester
 tools:
   - tools/verify_all.py
   - tools/infer_linter.py
@@ -21,6 +23,8 @@ tools:
   - tools/git_pre_commit_guard.py
   - tools/agent_canary.py
   - tools/spec_drift_sentinel.py
+  - tools/senior_code_review.py
+  - tools/debt_harvester.py
 ---
 
 # Quality Gatekeeper & Sentinel Agent
@@ -51,6 +55,8 @@ tools:
 - `tools/validate_groovy_scripts.py`: Static linter verifying syntax and brace balance in Groovy test scripts.
 - `tools/git_pre_commit_guard.py`: Pre-commit git hook preventing unverified code from being staged.
 - `tools/agent_canary.py`: Injects 8 failure vectors to benchmark MTTR and autonomous recovery rate.
+- `tools/senior_code_review.py`: 6-pillar code change review (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat) against git diff.
+- `tools/debt_harvester.py`: Harvests `shortcut:` technical debt markers across codebase into tracked debt ledger.
 
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 

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

@@ -1,42 +1,62 @@
 ---
 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
 
-> **Purpose:** Resolve overlapping trigger scopes between Project-Local Skills and External Plugins, eliminating context contagion, token bloat, and conflicting instructions.
+> **Purpose:** Resolve overlapping trigger scopes between Project-Local Skills and External Plugins, as well as distinct operational boundaries among internal skills — eliminating context contagion, token bloat, and conflicting instructions.
 
 ---
 
 ## 1. Non-Negotiable Precedence Order
 
-When executing tasks within automated testing repositories, Agent must strictly apply the following resolution order:
+When executing tasks within automated testing repositories, all AI Agents must strictly apply the following 3-tier hierarchy:
 
 ```text
-[Tier 1: Project-Local Skills] (.agent/skills/*) 
-       v (Higher priority - Specialized & Context-Aware)
+[Tier 1: Project-Local Skills] (.agents/skills/*) 
+       v (Highest priority — Specialized, Context-Aware & Clean POM Enforced)
 [Tier 2: Core Project Rules] (.agents/rules/*)
-       v
-[Tier 3: External Plugin Skills] (antigravity-testing-kit, chrome-devtools-plugin)
+       v (Mandatory operating invariants & behavioral guardrails)
+[Tier 3: External Plugin Skills] (antigravity-testing-kit, chrome-devtools-plugin, generic plugins)
+       v (Suppressed whenever a Tier 1 skill exists)
 ```
 
 ---
 
-## 2. Specific Skill Mapping & Exclusion Matrix
+## 2. External Plugin Suppression Matrix (Tier 1 vs Tier 3)
 
-| Task Type | REQUIRED Skill (Tier 1) | EXCLUDED / SUPPRESSED Skill (Tier 3) | Reason |
+When an external plugin offers a capability that overlaps with a specialized Synapse Hub skill, the external skill is **strictly suppressed**:
+
+| Task Domain | REQUIRED Skill (Tier 1) | SUPPRESSED Skill (Tier 3) | Architectural Reason |
+|---|---|---|---|
+| **POM & Test Authoring** | `clean-pom-crafter`<br/>`lam-script-generator` | `QA Automation Engineer`, `Test Generator` | Generic plugins generate raw XPaths and Selenium boilerplate; Hub strictly enforces Flat Architecture and zero raw locators in scripts. |
+| **Code Change Review** | `senior-code-review` | `Generic PR Reviewer`, `Code Reviewer` | Evaluates 6 pillars (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat) specifically against Git Diff. |
+| **Locator Healing & Diffing** | `self-healing-locator`<br/>`failure-autopsy-and-healing` | `Locator Healer Agent` | Uses token-efficient semantic AOM diffing (Role > Label > TestId) instead of dumping thousands of raw HTML lines. |
+| **Flaky Test Triage & RCA** | `failure-autopsy-and-healing`<br/>`flaky-test-sentinel-and-quarantine` | `Flaky Test Analyzer` | Triage occurs via 0-token JUnit XML parsing, screenshot autopsy, and SQLite episodic memory cache (`global_cache.db`). |
+| **Live Probing & Inspection** | `playwright-live-interaction` | `Smart Locator Agent` | Direct CDP network idle 0, dynamic overlay detachment, and in-browser helper integration under 200ms. |
+| **Accessibility (WCAG)** | `wcag-audit-patterns` *(Guideline)* | `a11y-debugging` *(Tooling Only)* | `wcag-audit-patterns` enforces WCAG 2.2 A/AA criteria; Chrome DevTools MCP is used strictly for low-level node inspection. |
+
+---
+
+## 3. Internal Inter-Skill Coordination & Boundary Separation
+
+To prevent decision paralysis among internal skills in `.agents/skills/`, agents must strictly adhere to the following boundary matrix:
+
+| Functional Area | Primary Skill | Sibling Skill | Distinct Responsibility & Hand-Off |
 |---|---|---|---|
-| **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. |
+| **Code Creation** | `lean-code-ladder` | `surgical-coding-principles` | • `lean-code-ladder` governs **what to build** (descends 7-rung ladder, selects smallest working solution).<br/>• `surgical-coding-principles` governs **where to touch** (keeps git diff surgical, no unrelated file edits). |
+| **Technical Debt** | `technical-debt-harvester` | `code-refactoring-refactor-clean` | • `technical-debt-harvester` is the **accountant** (scans and tracks `shortcut:` comments in Markdown ledgers).<br/>• `code-refactoring-refactor-clean` is the **surgeon** (executes SOLID refactoring and code smell remediation). |
+| **Quality Review** | `senior-code-review` | `review-spec` (`goldfish_review`) | • `senior-code-review` audits **Source Code Diffs** (uncommitted / staged git changes).<br/>• `review-spec` audits **Requirements & User Stories** in a 0-context stress-test (Elephant-Goldfish model). |
+| **System Audit** | `repo-quality-audit` | `analyze_project` (`tools/`) | • `analyze_project.py` produces **deterministic facts** (AST map, env check, data flow, 9 gates DoD).<br/>• `repo-quality-audit` applies **senior engineering judgment** (evaluates real load, ranks *"Fix #1 first"*). |
+| **API Testing** | `api-spec-to-e2e-matrix` | `api-network-mocking-interception` | • `api-spec-to-e2e-matrix` compiles **test matrices** from OpenAPI specs.<br/>• `api-network-mocking-interception` stubs routes and injects **chaos network faults** during UI/API test runs. |
+| **Failure Analysis** | `self-healing-locator` | `failure-autopsy-and-healing` | • `self-healing-locator` fixes **individual broken Page Class selectors**.<br/>• `failure-autopsy-and-healing` triages **suite-wide run crashes**, JUnit XML reports, and logs. |
+| **DoD Verification** | `verification-before-completion` | `antigravity-test-sentinel` | • `verification-before-completion` enforces the **evidence protocol** (fresh command output required in session).<br/>• `antigravity-test-sentinel` is the **hard gatekeeper** (blocks task completion until all 9 Quality Gates pass). |
 
 ---
 
-## 3. Strict Prohibitions
+## 4. 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).
+1. **Zero Generic Test Boilerplate:** Never generate legacy Selenium, Cucumber, or Object Repository (`findTestObject`) code from external plugins.
+2. **Zero Raw HTML Dumps:** Never dump full HTML trees into context for locator healing; always extract compact AOM subtrees (< 500 tokens).
+3. **Zero Unverified Assertions:** Never complete a code or test task without executing fresh verification via `tools/verify_all.py`.

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

@@ -57,6 +57,8 @@ This rule governs all AI Agents operating on the repository. It mandates strict
 | :--- | :--- | :--- |
 | **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. |
+| **User requests: "review code" / "review diff" / "senior review"** | `python3 tools/senior_code_review.py` | 6-pillar code change review (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat). |
+| **User requests: "scan debt" / "list shortcuts" / "harvest debt"** | `python3 tools/debt_harvester.py` | Harvest `shortcut:` technical debt markers across repo into tracked markdown ledger. |
 | **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. |

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/.cursor/rules/synapse-qa.mdc

@@ -18,6 +18,7 @@ Attribution notices must be preserved.
 ## Core Rules
 1. **Clean POM Architecture:** No raw selectors (XPath/CSS) in test scripts. All selectors belong in Page Classes extending BasePage.
 2. **Truth Anchor:** Never fake test passes. Report genuine defects.
-3. **Smart Wait:** Prohibit static delays (`Thread.sleep`). Use dynamic smart waits.
-4. **Idempotent Test Data:** Prefix with `AUTO_` and dynamic timestamps; teardown after creation.
-5. **Bilingual Discipline:** Converse in Vietnamese; write code and git commits strictly in English.
+3. **Lean Senior Dev:** The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
+4. **Smart Wait:** Prohibit static delays (`Thread.sleep`). Use dynamic smart waits.
+5. **Idempotent Test Data:** Prefix with `AUTO_` and dynamic timestamps; teardown after creation.
+6. **Bilingual Discipline:** Converse in Vietnamese; write code and git commits strictly in English.

package/.cursorrules

@@ -22,5 +22,6 @@
 - Always read and follow AGENTS.md for operating standards.
 - Communicate with the user in Vietnamese; avoid unnecessary technical jargon overload ("don't be too tech"). All code, tests, and docs stay in English.
 - Enforce Clean POM Flat Architecture: all locators encapsulated in Page Classes.
+- Lean Senior Dev: The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
 - Zero fake passes: test assertions must strictly validate real state.
 - Before completing code changes, run: python tools/verify_all.py

package/.windsurfrules

@@ -21,5 +21,6 @@
 
 - Communicate with the user in Vietnamese; avoid unnecessary technical jargon overload ("don't be too tech"). All code, tests, and docs stay in English.
 - Adhere to Clean Page Object Model (POM) Flat Architecture.
+- Lean Senior Dev: Solve problems with minimum code via 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
 - Zero fake passes and zero swallowed exceptions.
 - Run Definition of Done verification: python tools/verify_all.py