synapse-hub 2.2.4 → 2.4.1

package/.agents/skills/katalon-cli-runner/references/katalon-api.md

@@ -1,155 +1,155 @@
-# Katalon Built-in Keywords API Reference
-
-This document provides a reference for Katalon Studio's most commonly used built-in keywords.
-
-## WebUI Keywords
-
-Katalon's WebUI keywords are accessed via `com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords` (commonly imported as `WebUI`).
-
-### Navigation Keywords
-
-- `WebUI.openBrowser(url)` - Open a browser and navigate to URL
-- `WebUI.navigateToUrl(url)` - Navigate to a URL in the current browser
-- `WebUI.closeBrowser()` - Close the current browser
-- `WebUI.back()` - Navigate back in browser history
-- `WebUI.forward()` - Navigate forward in browser history
-- `WebUI.refresh()` - Refresh the current page
-- `WebUI.switchToWindowIndex(index)` - Switch to a browser window by index
-- `WebUI.switchToWindowTitle(title)` - Switch to a browser window by title
-- `WebUI.switchToWindowUrl(url)` - Switch to a browser window by URL
-
-### Element Interaction Keywords
-
-- `WebUI.click(testObject)` - Click on an element
-- `WebUI.doubleClick(testObject)` - Double-click on an element
-- `WebUI.rightClick(testObject)` - Right-click on an element
-- `WebUI.setText(testObject, text)` - Set text for an input field
-- `WebUI.sendKeys(testObject, text)` - Send keyboard input to an element
-- `WebUI.clearText(testObject)` - Clear text from an input field
-- `WebUI.selectOptionByValue(testObject, value, isRegex)` - Select dropdown option by value
-- `WebUI.selectOptionByLabel(testObject, label, isRegex)` - Select dropdown option by label
-- `WebUI.selectOptionByIndex(testObject, index)` - Select dropdown option by index
-- `WebUI.check(testObject)` - Check a checkbox
-- `WebUI.uncheck(testObject)` - Uncheck a checkbox
-- `WebUI.uploadFile(testObject, filePath)` - Upload a file to a file input
-
-### Wait Keywords
-
-- `WebUI.waitForElementPresent(testObject, timeoutInSeconds)` - Wait for element to be present in DOM
-- `WebUI.waitForElementVisible(testObject, timeoutInSeconds)` - Wait for element to be visible
-- `WebUI.waitForElementClickable(testObject, timeoutInSeconds)` - Wait for element to be clickable
-- `WebUI.waitForElementNotPresent(testObject, timeoutInSeconds)` - Wait for element to not be present
-- `WebUI.waitForElementNotVisible(testObject, timeoutInSeconds)` - Wait for element to not be visible
-- `WebUI.waitForPageLoad(timeoutInSeconds)` - Wait for page to fully load
-- `WebUI.delay(timeInSeconds)` - Pause execution for specified seconds
-
-### Verification Keywords
-
-- `WebUI.verifyElementPresent(testObject, timeoutInSeconds)` - Verify element is present
-- `WebUI.verifyElementVisible(testObject)` - Verify element is visible
-- `WebUI.verifyElementClickable(testObject)` - Verify element is clickable
-- `WebUI.verifyElementNotPresent(testObject, timeoutInSeconds)` - Verify element is not present
-- `WebUI.verifyElementText(testObject, expectedText)` - Verify element contains expected text
-- `WebUI.verifyTextPresent(text, isRegex)` - Verify text is present on the page
-- `WebUI.verifyElementAttributeValue(testObject, attribute, expectedValue, timeoutInSeconds)` - Verify element attribute value
-
-### Get Keywords
-
-- `WebUI.getText(testObject)` - Get text content of an element
-- `WebUI.getAttribute(testObject, attribute)` - Get attribute value of an element
-- `WebUI.getCSSValue(testObject, propertyName)` - Get CSS property value
-- `WebUI.getUrl()` - Get current page URL
-- `WebUI.getWindowTitle()` - Get current window title
-
-### Screenshot Keywords
-
-- `WebUI.takeScreenshot(filePath)` - Take a screenshot and save to file
-- `WebUI.takeFullPageScreenshot(filePath)` - Take a full-page screenshot
-
-## Mobile Keywords
-
-Katalon's Mobile keywords are accessed via `com.kms.katalon.core.mobile.keyword.MobileBuiltInKeywords` (commonly imported as `Mobile`).
-
-### Common Mobile Keywords
-
-- `Mobile.startApplication(appPath)` - Start a mobile application
-- `Mobile.closeApplication()` - Close the current application
-- `Mobile.tap(testObject, timeout)` - Tap on a mobile element
-- `Mobile.setText(testObject, text, timeout)` - Set text in a mobile input
-- `Mobile.getText(testObject, timeout)` - Get text from a mobile element
-- `Mobile.verifyElementExist(testObject, timeout)` - Verify mobile element exists
-- `Mobile.scrollToText(text)` - Scroll until specified text is visible
-- `Mobile.swipe(startX, startY, endX, endY)` - Perform a swipe gesture
-
-## Web Service (API) Keywords
-
-Katalon's Web Service keywords are accessed via `com.kms.katalon.core.webservice.keyword.WSBuiltInKeywords` (commonly imported as `WS`).
-
-### API Keywords
-
-- `WS.sendRequest(requestObject)` - Send a web service request
-- `WS.verifyResponseStatusCode(response, statusCode)` - Verify HTTP response status code
-- `WS.verifyElementPropertyValue(response, locator, expectedValue)` - Verify JSON/XML element value
-- `WS.getElementPropertyValue(response, locator)` - Get value from JSON/XML response
-- `WS.verifyElementsCount(response, locator, expectedCount)` - Verify count of elements in response
-
-## Utility Keywords
-
-### Checkpoint Keywords
-
-- `findCheckpoint(checkpointName)` - Find a checkpoint by name
-
-### Test Case Keywords
-
-- `findTestCase(testCasePath)` - Find a test case by path
-- `WebUI.callTestCase(testCase, variables)` - Call another test case
-
-### Test Data Keywords
-
-- `findTestData(testDataName)` - Find test data by name
-
-### Object Repository Keywords
-
-- `findTestObject(objectPath)` - Find a test object from Object Repository
-- `findTestObject(objectPath, variables)` - Find a test object with variable bindings
-
-## Global Variables
-
-Access global variables defined in profiles using `internal.GlobalVariable`:
-
-```groovy
-import internal.GlobalVariable
-
-// Access a global variable
-String url = GlobalVariable.baseUrl
-String username = GlobalVariable.username
-int timeout = GlobalVariable.waitTimeout
-```
-
-## Failure Handling
-
-Control how test execution handles failures using `com.kms.katalon.core.model.FailureHandling`:
-
-- `FailureHandling.STOP_ON_FAILURE` - Stop test execution on failure (default)
-- `FailureHandling.CONTINUE_ON_FAILURE` - Continue execution even if step fails
-- `FailureHandling.OPTIONAL` - Mark step as optional, continue regardless of result
-
-Example:
-```groovy
-WebUI.verifyElementPresent(findTestObject('optionalElement'), 5, FailureHandling.OPTIONAL)
-```
-
-## Annotations for Custom Keywords
-
-When creating custom keywords, use the `@Keyword` annotation:
-
-```groovy
-import com.kms.katalon.core.annotation.Keyword
-
-class MyKeywords {
-    @Keyword
-    def myCustomKeyword(String param) {
-        // Implementation
-    }
-}
-```
+# Katalon Built-in Keywords API Reference
+
+This document provides a reference for Katalon Studio's most commonly used built-in keywords.
+
+## WebUI Keywords
+
+Katalon's WebUI keywords are accessed via `com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords` (commonly imported as `WebUI`).
+
+### Navigation Keywords
+
+- `WebUI.openBrowser(url)` - Open a browser and navigate to URL
+- `WebUI.navigateToUrl(url)` - Navigate to a URL in the current browser
+- `WebUI.closeBrowser()` - Close the current browser
+- `WebUI.back()` - Navigate back in browser history
+- `WebUI.forward()` - Navigate forward in browser history
+- `WebUI.refresh()` - Refresh the current page
+- `WebUI.switchToWindowIndex(index)` - Switch to a browser window by index
+- `WebUI.switchToWindowTitle(title)` - Switch to a browser window by title
+- `WebUI.switchToWindowUrl(url)` - Switch to a browser window by URL
+
+### Element Interaction Keywords
+
+- `WebUI.click(testObject)` - Click on an element
+- `WebUI.doubleClick(testObject)` - Double-click on an element
+- `WebUI.rightClick(testObject)` - Right-click on an element
+- `WebUI.setText(testObject, text)` - Set text for an input field
+- `WebUI.sendKeys(testObject, text)` - Send keyboard input to an element
+- `WebUI.clearText(testObject)` - Clear text from an input field
+- `WebUI.selectOptionByValue(testObject, value, isRegex)` - Select dropdown option by value
+- `WebUI.selectOptionByLabel(testObject, label, isRegex)` - Select dropdown option by label
+- `WebUI.selectOptionByIndex(testObject, index)` - Select dropdown option by index
+- `WebUI.check(testObject)` - Check a checkbox
+- `WebUI.uncheck(testObject)` - Uncheck a checkbox
+- `WebUI.uploadFile(testObject, filePath)` - Upload a file to a file input
+
+### Wait Keywords
+
+- `WebUI.waitForElementPresent(testObject, timeoutInSeconds)` - Wait for element to be present in DOM
+- `WebUI.waitForElementVisible(testObject, timeoutInSeconds)` - Wait for element to be visible
+- `WebUI.waitForElementClickable(testObject, timeoutInSeconds)` - Wait for element to be clickable
+- `WebUI.waitForElementNotPresent(testObject, timeoutInSeconds)` - Wait for element to not be present
+- `WebUI.waitForElementNotVisible(testObject, timeoutInSeconds)` - Wait for element to not be visible
+- `WebUI.waitForPageLoad(timeoutInSeconds)` - Wait for page to fully load
+- `WebUI.delay(timeInSeconds)` - Pause execution for specified seconds
+
+### Verification Keywords
+
+- `WebUI.verifyElementPresent(testObject, timeoutInSeconds)` - Verify element is present
+- `WebUI.verifyElementVisible(testObject)` - Verify element is visible
+- `WebUI.verifyElementClickable(testObject)` - Verify element is clickable
+- `WebUI.verifyElementNotPresent(testObject, timeoutInSeconds)` - Verify element is not present
+- `WebUI.verifyElementText(testObject, expectedText)` - Verify element contains expected text
+- `WebUI.verifyTextPresent(text, isRegex)` - Verify text is present on the page
+- `WebUI.verifyElementAttributeValue(testObject, attribute, expectedValue, timeoutInSeconds)` - Verify element attribute value
+
+### Get Keywords
+
+- `WebUI.getText(testObject)` - Get text content of an element
+- `WebUI.getAttribute(testObject, attribute)` - Get attribute value of an element
+- `WebUI.getCSSValue(testObject, propertyName)` - Get CSS property value
+- `WebUI.getUrl()` - Get current page URL
+- `WebUI.getWindowTitle()` - Get current window title
+
+### Screenshot Keywords
+
+- `WebUI.takeScreenshot(filePath)` - Take a screenshot and save to file
+- `WebUI.takeFullPageScreenshot(filePath)` - Take a full-page screenshot
+
+## Mobile Keywords
+
+Katalon's Mobile keywords are accessed via `com.kms.katalon.core.mobile.keyword.MobileBuiltInKeywords` (commonly imported as `Mobile`).
+
+### Common Mobile Keywords
+
+- `Mobile.startApplication(appPath)` - Start a mobile application
+- `Mobile.closeApplication()` - Close the current application
+- `Mobile.tap(testObject, timeout)` - Tap on a mobile element
+- `Mobile.setText(testObject, text, timeout)` - Set text in a mobile input
+- `Mobile.getText(testObject, timeout)` - Get text from a mobile element
+- `Mobile.verifyElementExist(testObject, timeout)` - Verify mobile element exists
+- `Mobile.scrollToText(text)` - Scroll until specified text is visible
+- `Mobile.swipe(startX, startY, endX, endY)` - Perform a swipe gesture
+
+## Web Service (API) Keywords
+
+Katalon's Web Service keywords are accessed via `com.kms.katalon.core.webservice.keyword.WSBuiltInKeywords` (commonly imported as `WS`).
+
+### API Keywords
+
+- `WS.sendRequest(requestObject)` - Send a web service request
+- `WS.verifyResponseStatusCode(response, statusCode)` - Verify HTTP response status code
+- `WS.verifyElementPropertyValue(response, locator, expectedValue)` - Verify JSON/XML element value
+- `WS.getElementPropertyValue(response, locator)` - Get value from JSON/XML response
+- `WS.verifyElementsCount(response, locator, expectedCount)` - Verify count of elements in response
+
+## Utility Keywords
+
+### Checkpoint Keywords
+
+- `findCheckpoint(checkpointName)` - Find a checkpoint by name
+
+### Test Case Keywords
+
+- `findTestCase(testCasePath)` - Find a test case by path
+- `WebUI.callTestCase(testCase, variables)` - Call another test case
+
+### Test Data Keywords
+
+- `findTestData(testDataName)` - Find test data by name
+
+### Object Repository Keywords
+
+- `findTestObject(objectPath)` - Find a test object from Object Repository
+- `findTestObject(objectPath, variables)` - Find a test object with variable bindings
+
+## Global Variables
+
+Access global variables defined in profiles using `internal.GlobalVariable`:
+
+```groovy
+import internal.GlobalVariable
+
+// Access a global variable
+String url = GlobalVariable.baseUrl
+String username = GlobalVariable.username
+int timeout = GlobalVariable.waitTimeout
+```
+
+## Failure Handling
+
+Control how test execution handles failures using `com.kms.katalon.core.model.FailureHandling`:
+
+- `FailureHandling.STOP_ON_FAILURE` - Stop test execution on failure (default)
+- `FailureHandling.CONTINUE_ON_FAILURE` - Continue execution even if step fails
+- `FailureHandling.OPTIONAL` - Mark step as optional, continue regardless of result
+
+Example:
+```groovy
+WebUI.verifyElementPresent(findTestObject('optionalElement'), 5, FailureHandling.OPTIONAL)
+```
+
+## Annotations for Custom Keywords
+
+When creating custom keywords, use the `@Keyword` annotation:
+
+```groovy
+import com.kms.katalon.core.annotation.Keyword
+
+class MyKeywords {
+    @Keyword
+    def myCustomKeyword(String param) {
+        // Implementation
+    }
+}
+```

package/.agents/skills/katalon-cli-runner/references/runner_commands.md

@@ -1,67 +1,67 @@
-# CLI Runner Commands & Enterprise Test Suites Registry
-
-Reference documentation for the `katalon-cli-runner` skill.
-
----
-
-## 1. Environment Variable Configuration (.env)
-```bash
-KATALON_API_KEY="your_actual_api_key_here"
-KATALON_PROJECT_PATH="/path/to/project"
-TELEGRAM_BOT_TOKEN="your_bot_token"
-TELEGRAM_CHAT_ID="your_chat_id"
-```
-
----
-
-## 2. Platform-Specific Execution Commands (KRE CLI)
-
-### 2.1. Windows Environment (PowerShell Runner)
-```powershell
-# Run Test Suite with API Key
-powershell -ExecutionPolicy Bypass -File .\run_tests_windows.ps1 -Suite "Test Suites/07_QuanTriDuLieu" -ApiKey $env:KATALON_API_KEY
-
-# Run single Test Suite for debugging:
-powershell -ExecutionPolicy Bypass -File .\run_tests_windows.ps1 -Suite "Test Suites/Group_07_01_CumCongNghiep"
-```
-
-### 2.2. macOS / Linux CLI (Headless Full HD)
-```bash
-# Run Test Suite
-katalonc \
-  -noSplash \
-  -runMode=console \
-  -projectPath="$(pwd)/project.prj" \
-  -retry=0 \
-  -testSuitePath="Test Suites/07_QuanTriDuLieu" \
-  -browserType="Chrome (headless)" \
-  -executionProfile="default" \
-  -apiKey="$KATALON_API_KEY" \
-  --args="-headless --window-size=1920,1080 --disable-gpu --no-sandbox --disable-dev-shm-usage"
-
-# Run single Test Case (Debug Mode):
-katalonc \
-  -noSplash \
-  -runMode=console \
-  -projectPath="$(pwd)/project.prj" \
-  -testCasePath="Test Cases/TC-1 Kiểm tra tạo mới thành công" \
-  -browserType="Chrome (headless)" \
-  -apiKey="$KATALON_API_KEY"
-```
-
----
-
-## 3. Standard Enterprise Test Suite Registry
-
-| Test Suite Name | Scale | Target Functional Module |
-| :--- | :---: | :--- |
-| `Test Suites/All_Tests` | Full Suite | All functional modules |
-| `Test Suites/01_QuanLyChiTieu` | 7 TCs | Target Planning |
-| `Test Suites/02_XacThucNguoiDung` | 5 TCs | User Authentication & Profiles |
-| `Test Suites/03_QuanTriHeThong` | 4 TCs | System Administration & Users |
-| `Test Suites/04_DanhMucDungChung` | 12 TCs | Common Categories (Departments, Roles) |
-| `Test Suites/05_DanhMucNganhCongThuong` | 64 TCs | 16 Industry Sub-Categories |
-| `Test Suites/06_QuyHoachCongThuong` | 30 TCs | Sector Planning |
-| `Test Suites/07_QuanTriDuLieu` | 125 TCs | Data Mining & GIS Maps |
-| `Test Suites/08_BaoCaoThongKe` | 2 TCs | Statistical Reports (Data & Permits) |
-| `Test Suites/09_ChiaSeDuLieu` | 10 TCs | Data Sharing & API Token Lifecycle |
+# CLI Runner Commands & Enterprise Test Suites Registry
+
+Reference documentation for the `katalon-cli-runner` skill.
+
+---
+
+## 1. Environment Variable Configuration (.env)
+```bash
+KATALON_API_KEY="your_actual_api_key_here"
+KATALON_PROJECT_PATH="/path/to/project"
+TELEGRAM_BOT_TOKEN="your_bot_token"
+TELEGRAM_CHAT_ID="your_chat_id"
+```
+
+---
+
+## 2. Platform-Specific Execution Commands (KRE CLI)
+
+### 2.1. Windows Environment (PowerShell Runner)
+```powershell
+# Run Test Suite with API Key
+powershell -ExecutionPolicy Bypass -File .\run_tests_windows.ps1 -Suite "Test Suites/07_QuanTriDuLieu" -ApiKey $env:KATALON_API_KEY
+
+# Run single Test Suite for debugging:
+powershell -ExecutionPolicy Bypass -File .\run_tests_windows.ps1 -Suite "Test Suites/Group_07_01_CumCongNghiep"
+```
+
+### 2.2. macOS / Linux CLI (Headless Full HD)
+```bash
+# Run Test Suite
+katalonc \
+  -noSplash \
+  -runMode=console \
+  -projectPath="$(pwd)/project.prj" \
+  -retry=0 \
+  -testSuitePath="Test Suites/07_QuanTriDuLieu" \
+  -browserType="Chrome (headless)" \
+  -executionProfile="default" \
+  -apiKey="$KATALON_API_KEY" \
+  --args="-headless --window-size=1920,1080 --disable-gpu --no-sandbox --disable-dev-shm-usage"
+
+# Run single Test Case (Debug Mode):
+katalonc \
+  -noSplash \
+  -runMode=console \
+  -projectPath="$(pwd)/project.prj" \
+  -testCasePath="Test Cases/TC-1 Kiểm tra tạo mới thành công" \
+  -browserType="Chrome (headless)" \
+  -apiKey="$KATALON_API_KEY"
+```
+
+---
+
+## 3. Standard Enterprise Test Suite Registry
+
+| Test Suite Name | Scale | Target Functional Module |
+| :--- | :---: | :--- |
+| `Test Suites/All_Tests` | Full Suite | All functional modules |
+| `Test Suites/01_QuanLyChiTieu` | 7 TCs | Target Planning |
+| `Test Suites/02_XacThucNguoiDung` | 5 TCs | User Authentication & Profiles |
+| `Test Suites/03_QuanTriHeThong` | 4 TCs | System Administration & Users |
+| `Test Suites/04_DanhMucDungChung` | 12 TCs | Common Categories (Departments, Roles) |
+| `Test Suites/05_DanhMucNganhCongThuong` | 64 TCs | 16 Industry Sub-Categories |
+| `Test Suites/06_QuyHoachCongThuong` | 30 TCs | Sector Planning |
+| `Test Suites/07_QuanTriDuLieu` | 125 TCs | Data Mining & GIS Maps |
+| `Test Suites/08_BaoCaoThongKe` | 2 TCs | Statistical Reports (Data & Permits) |
+| `Test Suites/09_ChiaSeDuLieu` | 10 TCs | Data Sharing & API Token Lifecycle |

package/.agents/skills/lam-script-generator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lam-script-generator
-description: "Transform user stories and acceptance criteria into Clean POM automation scripts."
+description: "Transform user stories and acceptance criteria into Clean POM automation scripts. Use when the user provides a user story, acceptance criteria, or requirement document that must become a runnable script."
 ---
 
 # LAM Script Generator — Large Action Model for Test Automation
@@ -80,3 +80,44 @@ IndustryDataPage.deleteRecordByCode(uniqueCode)
 - Zero raw XPaths, CSS selectors, or `findTestObject` in the generated script.
 - Always generate dynamic identifiers with prefixes via `BasePage.uniqueCode()`.
 - Always generate mandatory teardown cleanup for created entities.
+
+## 4. Proven-vs-Owed Traceability Pipeline
+
+> *Borrowed and adapted from the Kane CLI generate→execute→prove workflow (Apache-2.0, lambdatest/kane-cli).*
+
+Generated scripts must be traceable to the acceptance criteria they prove.
+For every user story, maintain the chain:
+
+```mermaid
+flowchart LR
+    Story["<b>User Story</b>"] --> UC["<b>Use Cases</b><br/>(each cites its source line)"]
+    UC --> AC["<b>Acceptance Criteria</b><br/>(Given/When/Then, testable)"]
+    AC --> SC["<b>Scenarios</b><br/>(happy + negative + boundary)"]
+    SC --> TC["<b>Automation Scripts</b><br/>(Clean POM, 0 raw XPath)"]
+    TC --> EV["<b>Proven vs Owed</b><br/>coverage per criterion"]
+```
+
+Rules:
+
+1. **Every generated script cites its criterion** — keep the AC id in the test
+   case name or a comment header; a script nobody can trace back is a liability.
+2. **Report coverage as proven vs owed, not test counts** — a criterion with no
+   passing automated script is *owed*; N scripts proving one criterion is waste.
+3. **Reconcile on requirement change** — when a story changes, re-run the chain
+   and mark stale scripts before trusting any green run.
+4. For BDD inputs, the `gherkin-to-suite` skill performs the AC→scenario
+   expansion deterministically (0-token); feed its Universal IR here for
+   codification.
+
+---
+
+## 5. Boundary vs `clean-pom-crafter` and `gherkin-to-suite`
+
+- **This skill** = natural-language story → action-sequence script skeleton
+  (the "what steps, in what order" reasoning layer).
+- **`clean-pom-crafter`** owns the Page Classes and locator discipline that the
+  skeleton's business-flow calls resolve against — never inline raw selectors
+  here.
+- **`gherkin-to-suite`** is the deterministic (0-token) alternative when
+  requirements already exist as `.feature` files; use it first, and feed its
+  Universal IR here only when story-level reasoning must fill the gaps.

package/.agents/skills/lam-script-generator/examples/user_story_sample.md

@@ -0,0 +1,8 @@
+# User Story: User Password Reset Flow
+As a registered customer,
+I want to request a password reset email,
+So that I can regain access if I forget my password.
+
+## Acceptance Criteria:
+1. Submitting registered email displays "Reset link dispatched".
+2. Submitting empty email highlights field in red with validation error.

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

@@ -0,0 +1,83 @@
+---
+name: lean-code-ladder
+description: "Apply a 7-rung reuse-first ladder so every new test-automation code path is the smallest complete change that fully solves the task. Use when adding helpers, Page Class methods, dependencies, or any new code where a shorter existing option might already exist."
+---
+
+# Lean Code Ladder — Enterprise Reuse-First Standard
+
+Specialized skill for minimizing newly written code in test automation projects: solve the whole problem with the least new code, then finish the change completely (callers, fixtures, and the small test that proves it).
+
+---
+
+## 1. The 7-Rung Ladder
+
+Before writing any new code, descend the ladder and take the **first rung that fully works**:
+
+| Rung | Question | Action |
+|:---:|---|---|
+| 0 | Does it need to exist? | Skip features, options, and flexibility nobody asked for; name what you skipped in one line. A vague request gets the smallest version that does the core job. |
+| 1 | Already in the codebase? | A helper, Page Class method, or fixture exists? Use it the way the surrounding code does. |
+| 2 | Standard library? | Use the language stdlib unless the project has its own equivalent. |
+| 3 | Platform / framework native? | A built-in of the test framework beats a hand-rolled widget (e.g. Playwright auto-waiting, `expect` web-first assertions). |
+| 4 | Installed dependency? | Use it. Never add a new dependency for a few lines. |
+| 5 | One line? | Can it be one line a reader gets at a glance? Then one line. |
+| 6 | Minimum new code | Write the minimum that works, and no more. |
+
+## 2. Reading Order Before Writing
+
+- Read the task and the code it touches. List every place the change must reach: callers, tests, fixtures, config, exports.
+- Check what the change could break: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
+
+## 3. Completeness Rules (Be Lazy About the Solution, Never About the Change)
+
+- Finish every part the task needs, including the callers, tests, and fixtures the change affects.
+- No abstraction, wrapper, option, config, or "for later" code nobody asked for. Keep values in the form the platform already gives. Deletion beats addition; keep the structure the codebase already has.
+- The shortest working diff wins, once everything it must touch is known. A one-liner that needs decoding is not short.
+- Comment only the "why" the code cannot show, in one line.
+- Bug fix: grep every caller of the touched function first, then fix the root cause once in the shared code (pair with `systematic-debugging`).
+- Code that is moved or merged keeps its error handling and validation.
+- Between options of equal size, take the one that is correct on edge cases.
+- New non-trivial logic (a branch, loop, parser, money/security path, or a whole new script) leaves one small test or assert-based self-check before it counts as finished; trivial changes need none.
+- A shortcut with a known limit gets a code comment: `shortcut: <the limit>, <when to upgrade>`.
+
+## 4. Never Cut (Hard Floor)
+
+The ladder minimizes code, never safety. The following are never removed or skipped in the name of leanness:
+
+- Validation at trust boundaries
+- Error handling that prevents data loss
+- Security checks (credential handling, authorization assertions)
+- Accessibility behavior
+- Anything the user explicitly asked for
+
+## 5. Evidence of Leanness
+
+- Run `python3 tools/infer_linter.py` after the change: zero fake-pass findings confirms the lean diff did not trade rigor for brevity.
+- Run the affected subset from `python3 tools/test_impact.py --git-diff` to prove the shortest diff still reaches everything it had to reach.
+- Lean code without its check is unfinished: Gate 8 (`tools/micro_mutator.py`, Mutation Score >= 80%) remains the floor for any assertion logic written on this ladder.
+
+## 6. Worked Comparison
+
+| Situation | Bloated answer | Lean answer |
+|---|---|---|
+| Need a date picker in a form test | 300-line custom calendar component | Native `<input type="date">` via the existing form helper (Rung 3) |
+| Need retry around a flaky API call | New generic retry framework with policy classes | The installed HTTP client's retry option (Rung 4) + one test |
+| Need a formatted timestamp in test data | New utility module | One line with the stdlib formatter (Rung 2) |
+
+## 7. Boundary vs Sibling Skills (Do Not Confuse)
+
+| Sibling | Owns | Hand-off |
+|---|---|---|
+| `surgical-coding-principles` | Diff discipline (every line traces to the request) | The ladder chooses the solution shape; surgical principles keep the diff clean |
+| `code-refactoring-refactor-clean` | Deliberate SOLID refactors of existing debt | Refactoring is not ladder work; only new/changed code descends the ladder |
+| `clean-pom-crafter` | Page Class architecture and locator tiers | Ladder applies inside and around Page Classes, not to their architecture contract |
+
+## 8. Reference Documentation
+
+- `python3 tools/infer_linter.py` — fake-pass scan for the new logic.
+- `python3 tools/test_impact.py --git-diff` — confirm the lean diff still covers all impacted tests.
+- `python3 tools/micro_mutator.py` — Gate 8 mutation floor (>= 80%) for non-trivial new logic.
+
+## 9. Attribution
+
+Adapted from **ponytail** (https://github.com/DietrichGebert/ponytail) — MIT License, Copyright (c) 2026 DietrichGebert. The lazy-senior ladder, completeness rules, and never-cut floor are re-scoped for enterprise test automation in Synapse Hub; wording, structure, and examples modified.

package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md

@@ -0,0 +1,37 @@
+# Example: Walking the Ladder for a Real Request
+
+Request: "In the login test suite, when login fails we need a readable message that includes the actual error returned by the app."
+
+## Descent
+
+| Rung | Checked | Result |
+|:---:|---|---|
+| 0 | Does it need to exist? | Yes — failure messages currently say only `Login failed`, which hides the app's actual error. Core job: include the returned error text. |
+| 1 | Already in the codebase? | YES — the login Page Class already builds an error context object with the app message; the assertion just never prints it. |
+| 2-4 | stdlib / platform / dependency | Not needed — rung 1 already solves it. |
+| 5-6 | One line / minimum | The fix becomes a one-line assertion change reusing the existing context object. |
+
+## Lean diff (the whole change)
+
+```text
+- expect(page).toHaveText('Login failed');
++ expect(page).toHaveText(`Login failed: ${errorContext.message}`);
+```
+
+Plus the completeness rule: one new test asserts the message embeds the app
+error for a rejected-credentials fixture, so the non-trivial path is covered.
+
+## Anti-example (what the ladder forbids)
+
+```text
++ class RetryableErrorContextFormatterFactory { ... }   // Rung 0 violation
++ npm install fancy-string-utils                        // Rung 4 violation
++ config option: errorMessageTemplateStyle: 'verbose' | 'compact'  // nobody asked
+```
+
+## Never-cut check (Rung floor)
+
+The shorter assertion still validates at the trust boundary (the app's
+returned error is rendered before being asserted), leaks no credentials into
+the failure message, and the fixture error text is sanitized synthetic data.
+Leanness changed the size of the diff, not the safety of the test.