chore: update plan and rulesets

2025-09-05 13:09:30 +00:00
parent cfeb920493
commit 74e4a20ef9
17 changed files with 1364 additions and 540 deletions
--- a/.cursor/rules/docs/markdown_templates.mdc
+++ b/.cursor/rules/docs/markdown_templates.mdc
@@ -192,6 +192,7 @@ Summary of key concepts and skills.

 Where to apply this knowledge next.
 ```
+
 - [ ] Integration tests
 - [ ] E2E tests

--- a/.cursor/rules/harbor_pilot_universal.mdc
+++ b/.cursor/rules/harbor_pilot_universal.mdc
@@ -19,6 +19,7 @@ inherits: base_context.mdc
 **Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human Competence First*

 > **Alignment with Base Context**
+>
 > - **Purpose fit**: Prioritizes human competence and collaboration while delivering reproducible artifacts.  
 > - **Output Contract**: This directive **adds universal constraints** for any technical topic while **inheriting** the Base Context contract sections.  
 > - **Toggles honored**: Uses the same toggle semantics; defaults above can be overridden by the caller.
@@ -26,9 +27,11 @@ inherits: base_context.mdc
 ---

 ## Objective
+
 Produce a **developer-grade, reproducible guide** for any technical topic that onboards a competent practitioner **without meta narration** and **with evidence-backed steps**.

 ## Scope & Constraints
+
 - **One Markdown document** as the deliverable.
 - Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid “today/yesterday”.
 - Include at least **one diagram** (Mermaid preferred). Choose the most fitting type:
@@ -41,6 +44,7 @@ Produce a **developer-grade, reproducible guide** for any technical topic that o
 - If something is unknown, output `TODO:<missing>` — **never invent**.

 ## Required Sections (extends Base Output Contract)
+
 Follow this exact order **after** the Base Contract’s **Objective → Result → Use/Run** headers:

 1. **Context & Scope**
@@ -69,16 +73,19 @@ Follow this exact order **after** the Base Contract’s **Objective → Result
    - Canonical docs, specs, tickets, prior analyses.

 > **Competence Hooks (per Base Context; keep lightweight):**
+>
 > - *Why this works* (≤3 bullets) — core invariants or guarantees.  
 > - *Common pitfalls* (≤3 bullets) — the traps we saw in evidence.  
 > - *Next skill unlock* (1 line) — the next capability to implement/learn.  
 > - *Teach-back* (1 line) — prompt the reader to restate the flow/architecture.

 > **Collaboration Hooks (per Base Context):**
+>
 > - Name reviewers for **Interfaces & Contracts** and the **diagram**.  
 > - Short **sign-off checklist** before merging/publishing the guide.

 ## Do / Don’t (Base-aligned)
+
 - **Do** quantify progress only against a defined scope with acceptance criteria.
 - **Do** include minimal sample payloads/headers or I/O schemas; redact sensitive values.
 - **Do** keep commentary lean; if timeboxed, move depth to **Deferred for depth**.
@@ -86,6 +93,7 @@ Follow this exact order **after** the Base Contract’s **Objective → Result
 - **Don’t** include IDE-specific chatter or internal rules unrelated to the task.

 ## Validation Checklist (self-check before returning)
+
 - [ ] All Required Sections present and ordered.  
 - [ ] Diagram compiles (basic Mermaid syntax) and fits the problem.  
 - [ ] If API-based, **Auth** and **Key Headers/Params** are listed for each endpoint.  
@@ -96,6 +104,7 @@ Follow this exact order **after** the Base Contract’s **Objective → Result
 - [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References).

 ## Universal Template (fill-in)
+
 ```markdown
 # <Title> — Working Notes (As of YYYY-MM-DDTHH:MMZ)

@@ -132,37 +141,46 @@ Follow this exact order **after** the Base Contract’s **Objective → Result
 ```

 ## Interfaces & Contracts
+
 ### If API-based
+
 | Step | Method | Path/URL | Auth | Key Headers/Params | Sample |
 |---|---|---|---|---|---|
 | <…> | <…> | <…> | <…> | <…> | below |

 ### If Data/Files
+
 | Source | Format | Schema/Columns | Size | Validation |
 |---|---|---|---|---|
 | <…> | <…> | <…> | <…> | <…> |

 ### If Systems/Hardware
+
 | Interface | Protocol | Timing/Voltage | Constraints | Notes |
 |---|---|---|---|---|
 | <…> | <…> | <…> | <…> | <…> |

 ## Repro: End-to-End Procedure
+
 ```bash
 # commands / curl examples (redacted where necessary)
 ```
+
 ```python
 # minimal client library example (language appropriate)
 ```
+
 > Expected output: <snippet/checks>

 ## What Works (Evidence)
+
 - ✅ <short statement>  
  - **Time**: <YYYY-MM-DDTHH:MMZ>  
  - **Evidence**: file/line/log or request id/status  
  - **Verify at**: <where>

 ## What Doesn’t (Evidence & Hypotheses)
+
 - ❌ <short failure> at `<component/endpoint/file>`  
  - **Time**: <YYYY-MM-DDTHH:MMZ>  
  - **Evidence**: <snippet/id/status>  
@@ -170,38 +188,46 @@ Follow this exact order **after** the Base Contract’s **Objective → Result
  - **Next probe**: <short>

 ## Risks, Limits, Assumptions
+
 <bullets: limits, security boundaries, retries/backoff, idempotency, SLOs>

 ## Next Steps
+
 | Owner | Task | Exit Criteria | Target Date (UTC) |
 |---|---|---|---|
 | <name> | <action> | <measurable outcome> | <YYYY-MM-DD> |

 ## References
+
 <links/titles>

 ## Competence Hooks
+
 - *Why this works*: <≤3 bullets>
 - *Common pitfalls*: <≤3 bullets>
 - *Next skill unlock*: <1 line>
 - *Teach-back*: <1 line>

 ## Collaboration Hooks
+
 - Reviewers: <names/roles>
 - Sign-off checklist: <≤5 checks>

 ## Assumptions & Limits
+
 <bullets>

 ## Deferred for depth
+
 <park deeper material here to respect timeboxing>
 ```

 ---

 **Notes for Implementers:**  
+
 - Respect Base *Do-Not* (no filler, no invented facts, no censorship).  
 - Prefer clarity over completeness when timeboxed; capture unknowns explicitly.
 - Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`)
 - Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`)
- Apply Playwright test investigation rules (see `.cursor/rules/playwright_test_investigation.mdc`)
+- Apply Playwright test investigation rules (see `.cursor/rules/playwright_test_investigation.mdc`)
--- a/.cursor/rules/meta_bug_diagnosis.mdc
+++ b/.cursor/rules/meta_bug_diagnosis.mdc
@@ -82,6 +82,7 @@ common investigation pitfalls.
 ### **Safe Diagnosis Commands**

 ✅ **Safe to use during diagnosis:**
+
 - `npm run lint-fix` - Syntax and style checking
 - `npm run type-check` - TypeScript validation (if available)
 - `git status` - Version control status
@@ -90,6 +91,7 @@ common investigation pitfalls.
 - `grep_search` - Text pattern searching

 ❌ **Never use during diagnosis:**
+
 - `npm run build:web` - Blocks chat
 - `npm run build:electron` - Blocks chat  
 - `npm run build:capacitor` - Blocks chat
--- a/.cursor/rules/meta_core_always_on.mdc
+++ b/.cursor/rules/meta_core_always_on.mdc
@@ -36,6 +36,7 @@ that are essential for all AI interactions.
 **This meta-rule enforces current workflow mode constraints for all interactions:**

 ### **Current Workflow State**
+
 ```json
 {
  "workflowState": {
@@ -62,26 +63,31 @@ that are essential for all AI interactions.
 ### **Mode-Specific Enforcement**

 **Diagnosis Mode (read_only):**
+
 - ❌ **Forbidden**: File modification, code creation, build commands, git commits
 - ✅ **Allowed**: File reading, code analysis, investigation, documentation
 - **Response**: Guide user toward investigation and analysis, not implementation

 **Fixing Mode (implementation):**
+
 - ✅ **Allowed**: File modification, code creation, build commands, testing, git commits
 - ❌ **Forbidden**: None (full implementation mode)
 - **Response**: Proceed with implementation and testing

 **Planning Mode (design_only):**
+
 - ❌ **Forbidden**: Implementation, coding, building, deployment
 - ✅ **Allowed**: Analysis, design, estimation, documentation, architecture
 - **Response**: Focus on planning and design, not implementation

 **Research Mode (investigation):**
+
 - ❌ **Forbidden**: File modification, implementation, deployment
 - ✅ **Allowed**: Investigation, analysis, research, documentation
 - **Response**: Focus on investigation and analysis

 **Documentation Mode (writing_only):**
+
 - ❌ **Forbidden**: Implementation, coding, building, deployment
 - ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing
 - **Response**: Focus on documentation creation and improvement
--- a/.cursor/rules/meta_documentation.mdc
+++ b/.cursor/rules/meta_documentation.mdc
@@ -51,6 +51,7 @@ providing technical descriptions.
 ## When to Use

 **Use this meta-rule when**:
+
 - Writing new documentation
 - Updating existing documentation
 - Creating technical guides
@@ -107,6 +108,7 @@ providing technical descriptions.
 ### **Document Structure**

 **Mandatory Sections**:
+
 - **Overview**: Clear purpose and scope with educational context
 - **Why This Matters**: Business value and user benefit explanation
 - **Core Concepts**: Fundamental understanding before implementation
@@ -116,6 +118,7 @@ providing technical descriptions.
 - **Next Steps**: Where to go from here

 **Optional Sections**:
+
 - **Background**: Historical context and evolution
 - **Alternatives**: Other approaches and trade-offs
 - **Advanced Topics**: Deep dive into complex scenarios
@@ -124,6 +127,7 @@ providing technical descriptions.
 ### **Writing Style**

 **Educational Approach**:
+
 - **Conversational tone**: Write as if explaining to a colleague
 - **Progressive disclosure**: Start simple, add complexity gradually
 - **Active voice**: "You can do this" not "This can be done"
@@ -131,6 +135,7 @@ providing technical descriptions.
 - **Analogies**: Use familiar concepts to explain complex ideas

 **Technical Accuracy**:
+
 - **Precise language**: Use exact technical terms consistently
 - **Code examples**: Working, tested code snippets
 - **Version information**: Specify applicable versions and platforms
@@ -139,6 +144,7 @@ providing technical descriptions.
 ### **Content Quality Standards**

 **Educational Value**:
+
 - [ ] **Concept clarity**: Reader understands the fundamental idea
 - [ ] **Context relevance**: Reader knows when to apply the knowledge
 - [ ] **Practical application**: Reader can implement the solution
@@ -146,6 +152,7 @@ providing technical descriptions.
 - [ ] **Next steps**: Reader knows where to continue learning

 **Technical Accuracy**:
+
 - [ ] **Fact verification**: All technical details are correct
 - [ ] **Code validation**: Examples compile and run correctly
 - [ ] **Version compatibility**: Platform and version requirements clear
@@ -183,6 +190,7 @@ providing technical descriptions.
 ### **Review Checklist**

 **Educational Quality**:
+
 - [ ] **Clear learning objective**: What will the reader learn?
 - [ ] **Appropriate complexity**: Matches target audience knowledge
 - [ ] **Progressive disclosure**: Information builds logically
@@ -190,6 +198,7 @@ providing technical descriptions.
 - [ ] **Common questions**: Anticipates and answers reader questions

 **Technical Quality**:
+
 - [ ] **Accuracy**: All technical details verified
 - [ ] **Completeness**: Covers all necessary information
 - [ ] **Consistency**: Terminology and formatting consistent
--- a/.cursor/rules/playwright-test-investigation.mdc
+++ b/.cursor/rules/playwright-test-investigation.mdc
@@ -9,26 +9,31 @@ alwaysApply: false
 **Status**: 🎯 **ACTIVE** - Playwright test debugging guidelines

 ## Objective
+
 Provide systematic approach for investigating Playwright test failures with focus on UI element conflicts, timing issues, and selector ambiguity.

 ## Context & Scope
+
 - **Audience**: Developers debugging Playwright test failures
 - **In scope**: Test failure analysis, selector conflicts, UI state investigation, timing issues
 - **Out of scope**: Test writing best practices, CI/CD configuration

 ## Artifacts & Links
+
 - Test results: `test-results/` directory
 - Error context: `error-context.md` files with page snapshots
 - Trace files: `trace.zip` files for failed tests
 - HTML reports: Interactive test reports with screenshots

 ## Environment & Preconditions
+
 - OS/Runtime: Linux/Windows/macOS with Node.js
 - Versions: Playwright test framework, browser drivers
 - Services: Local test server (localhost:8080), test data setup
 - Auth mode: None required for test investigation

 ## Architecture / Process Overview
+
 Playwright test investigation follows a systematic diagnostic workflow that leverages built-in debugging tools and error context analysis.

 ```mermaid
@@ -57,6 +62,7 @@ flowchart TD
 ## Interfaces & Contracts

 ### Test Results Structure
+
 | Component | Format | Content | Validation |
 |---|---|---|---|
 | Error Context | Markdown | Page snapshot in YAML | Verify DOM state matches test expectations |
@@ -65,6 +71,7 @@ flowchart TD
 | JSON Results | JSON | Machine-readable results | Parse for automated analysis |

 ### Investigation Commands
+
 | Step | Command | Expected Output | Notes |
 |---|---|---|---|
 | Locate failed tests | `find test-results -name "*test-name*"` | Test result directories | Use exact test name patterns |
@@ -74,6 +81,7 @@ flowchart TD
 ## Repro: End-to-End Investigation Procedure

 ### 1. Locate Failed Test Results
+
 ```bash
 # Find all results for a specific test
 find test-results -name "*test-name*" -type d
@@ -83,6 +91,7 @@ find test-results -name "error-context.md" | head -5
 ```

 ### 2. Analyze Error Context
+
 ```bash
 # Read error context for specific test
 cat test-results/test-name-test-description-browser/error-context.md
@@ -92,6 +101,7 @@ grep -A 10 -B 5 "button.*Yes\|button.*No" test-results/*/error-context.md
 ```

 ### 3. Check Trace Files
+
 ```bash
 # List available trace files
 find test-results -name "*.zip" | grep trace
@@ -101,6 +111,7 @@ npx playwright show-trace test-results/test-name/trace.zip
 ```

 ### 4. Investigate Selector Issues
+
 ```typescript
 // Check for multiple elements with same text
 await page.locator('button:has-text("Yes")').count(); // Should be 1
@@ -110,6 +121,7 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 ```

 ## What Works (Evidence)
+
 - ✅ **Error context files** provide page snapshots showing exact DOM state at failure  
  - **Time**: 2025-08-21T14:22Z  
  - **Evidence**: `test-results/60-new-activity-New-offers-for-another-user-chromium/error-context.md` shows both alerts visible  
@@ -126,6 +138,7 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
  - **Verify at**: Error context markdown files

 ## What Doesn't (Evidence & Hypotheses)
+
 - ❌ **Generic selectors** fail with multiple similar elements at `test-playwright/testUtils.ts:161`  
  - **Time**: 2025-08-21T14:22Z  
  - **Evidence**: `button:has-text("Yes")` matches both "Yes" and "Yes, Export Data"  
@@ -139,12 +152,14 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
  - **Next probe**: Implement alert queuing or prevent overlapping alerts

 ## Risks, Limits, Assumptions
+
 - **Trace file size**: Large trace files may impact storage and analysis time
 - **Browser compatibility**: Trace viewer requires specific browser support
 - **Test isolation**: Shared state between tests may affect investigation results
 - **Timing sensitivity**: Tests may pass/fail based on system performance

 ## Next Steps
+
 | Owner | Task | Exit Criteria | Target Date (UTC) |
 |---|---|---|---|
 | Development Team | Fix test selectors for multiple alerts | All tests pass consistently | 2025-08-22 |
@@ -152,21 +167,25 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 | Development Team | Add test IDs to alert buttons | Unique selectors for all UI elements | 2025-08-28 |

 ## References
+
 - [Playwright Trace Viewer Documentation](https://playwright.dev/docs/trace-viewer)
 - [Playwright Test Results](https://playwright.dev/docs/test-reporters)
 - [Test Investigation Workflow](./research_diagnostic.mdc)

 ## Competence Hooks
+
 - **Why this works**: Systematic investigation leverages Playwright's built-in debugging tools to identify root causes
 - **Common pitfalls**: Generic selectors fail with multiple similar elements; timing issues create race conditions; alert stacking causes UI conflicts
 - **Next skill unlock**: Implement unique test IDs and handle alert dismissal order in test flows
 - **Teach-back**: "How would you investigate a Playwright test failure using error context, trace files, and page snapshots?"

 ## Collaboration Hooks
+
 - **Reviewers**: QA team, test automation engineers
 - **Sign-off checklist**: Error context analyzed, trace files reviewed, root cause identified, fix implemented and tested

 ## Assumptions & Limits
+
 - Test results directory structure follows Playwright conventions
 - Trace files are enabled in configuration (`trace: "retain-on-failure"`)
 - Error context files contain valid YAML page snapshots
@@ -178,6 +197,7 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 **Priority**: High  
 **Maintainer**: Development team  
 **Next Review**: 2025-09-21
+
 # Playwright Test Investigation — Harbor Pilot Directive

 **Author**: Matthew Raymer  
@@ -185,26 +205,31 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 **Status**: 🎯 **ACTIVE** - Playwright test debugging guidelines

 ## Objective
+
 Provide systematic approach for investigating Playwright test failures with focus on UI element conflicts, timing issues, and selector ambiguity.

 ## Context & Scope
+
 - **Audience**: Developers debugging Playwright test failures
 - **In scope**: Test failure analysis, selector conflicts, UI state investigation, timing issues
 - **Out of scope**: Test writing best practices, CI/CD configuration

 ## Artifacts & Links
+
 - Test results: `test-results/` directory
 - Error context: `error-context.md` files with page snapshots
 - Trace files: `trace.zip` files for failed tests
 - HTML reports: Interactive test reports with screenshots

 ## Environment & Preconditions
+
 - OS/Runtime: Linux/Windows/macOS with Node.js
 - Versions: Playwright test framework, browser drivers
 - Services: Local test server (localhost:8080), test data setup
 - Auth mode: None required for test investigation

 ## Architecture / Process Overview
+
 Playwright test investigation follows a systematic diagnostic workflow that leverages built-in debugging tools and error context analysis.

 ```mermaid
@@ -233,6 +258,7 @@ flowchart TD
 ## Interfaces & Contracts

 ### Test Results Structure
+
 | Component | Format | Content | Validation |
 |---|---|---|---|
 | Error Context | Markdown | Page snapshot in YAML | Verify DOM state matches test expectations |
@@ -241,6 +267,7 @@ flowchart TD
 | JSON Results | JSON | Machine-readable results | Parse for automated analysis |

 ### Investigation Commands
+
 | Step | Command | Expected Output | Notes |
 |---|---|---|---|
 | Locate failed tests | `find test-results -name "*test-name*"` | Test result directories | Use exact test name patterns |
@@ -250,6 +277,7 @@ flowchart TD
 ## Repro: End-to-End Investigation Procedure

 ### 1. Locate Failed Test Results
+
 ```bash
 # Find all results for a specific test
 find test-results -name "*test-name*" -type d
@@ -259,6 +287,7 @@ find test-results -name "error-context.md" | head -5
 ```

 ### 2. Analyze Error Context
+
 ```bash
 # Read error context for specific test
 cat test-results/test-name-test-description-browser/error-context.md
@@ -268,6 +297,7 @@ grep -A 10 -B 5 "button.*Yes\|button.*No" test-results/*/error-context.md
 ```

 ### 3. Check Trace Files
+
 ```bash
 # List available trace files
 find test-results -name "*.zip" | grep trace
@@ -277,6 +307,7 @@ npx playwright show-trace test-results/test-name/trace.zip
 ```

 ### 4. Investigate Selector Issues
+
 ```typescript
 // Check for multiple elements with same text
 await page.locator('button:has-text("Yes")').count(); // Should be 1
@@ -286,6 +317,7 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 ```

 ## What Works (Evidence)
+
 - ✅ **Error context files** provide page snapshots showing exact DOM state at failure  
  - **Time**: 2025-08-21T14:22Z  
  - **Evidence**: `test-results/60-new-activity-New-offers-for-another-user-chromium/error-context.md` shows both alerts visible  
@@ -302,6 +334,7 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
  - **Verify at**: Error context markdown files

 ## What Doesn't (Evidence & Hypotheses)
+
 - ❌ **Generic selectors** fail with multiple similar elements at `test-playwright/testUtils.ts:161`  
  - **Time**: 2025-08-21T14:22Z  
  - **Evidence**: `button:has-text("Yes")` matches both "Yes" and "Yes, Export Data"  
@@ -315,12 +348,14 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
  - **Next probe**: Implement alert queuing or prevent overlapping alerts

 ## Risks, Limits, Assumptions
+
 - **Trace file size**: Large trace files may impact storage and analysis time
 - **Browser compatibility**: Trace viewer requires specific browser support
 - **Test isolation**: Shared state between tests may affect investigation results
 - **Timing sensitivity**: Tests may pass/fail based on system performance

 ## Next Steps
+
 | Owner | Task | Exit Criteria | Target Date (UTC) |
 |---|---|---|---|
 | Development Team | Fix test selectors for multiple alerts | All tests pass consistently | 2025-08-22 |
@@ -328,21 +363,25 @@ await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes"
 | Development Team | Add test IDs to alert buttons | Unique selectors for all UI elements | 2025-08-28 |

 ## References
+
 - [Playwright Trace Viewer Documentation](https://playwright.dev/docs/trace-viewer)
 - [Playwright Test Results](https://playwright.dev/docs/test-reporters)
 - [Test Investigation Workflow](./research_diagnostic.mdc)

 ## Competence Hooks
+
 - **Why this works**: Systematic investigation leverages Playwright's built-in debugging tools to identify root causes
 - **Common pitfalls**: Generic selectors fail with multiple similar elements; timing issues create race conditions; alert stacking causes UI conflicts
 - **Next skill unlock**: Implement unique test IDs and handle alert dismissal order in test flows
 - **Teach-back**: "How would you investigate a Playwright test failure using error context, trace files, and page snapshots?"

 ## Collaboration Hooks
+
 - **Reviewers**: QA team, test automation engineers
 - **Sign-off checklist**: Error context analyzed, trace files reviewed, root cause identified, fix implemented and tested

 ## Assumptions & Limits
+
 - Test results directory structure follows Playwright conventions
 - Trace files are enabled in configuration (`trace: "retain-on-failure"`)
 - Error context files contain valid YAML page snapshots