@bugmole/cli 0.4.0

package/spec/plans/owner-operations.flow.yaml

@@ -0,0 +1,20 @@
+version: 1
+id: owner-operations
+name: "Journey: owner-operations"
+description: Generated plan for journey owner-operations with actor owner
+suites:
+  - id: default
+    runs: on_demand
+    journeys:
+      - id: owner-operations
+        actor: owner
+        goal: "Complete journey: owner-operations"
+        capabilities_required: []
+        preconditions:
+          - Test tenant / sandbox is active
+          - Actor account exists
+        steps:
+          - action: observe:owner-operations
+            proofs:
+              - type: dom
+                expects: "discovered journey screen: owner-operations"

package/spec/project_config.yaml

@@ -0,0 +1,55 @@
+# Project Configuration for Bugmole MCP
+
+project:
+  workspace_id: "demo-workspace"
+  workspace_name: "Demo workspace"
+  name: "Arion Rent"
+  type: "monorepo"
+  base_url: "http://localhost:3010"
+  evidence_manifest: "../../qa/browser-evidence.json"
+  evidence_screenshots: "../../qa/screenshots"
+
+applications:
+  - id: "web"
+    name: "web"
+    default: true
+    type: "frontend"
+    framework: "Next.js App Router"
+    port: 3010
+    base_url: "http://localhost:3010"
+    start_command: "npm run dev -- -p 3010"
+    location: "."
+
+startup:
+  prerequisites:
+    - "Node.js and npm dependencies installed from the workspace root"
+    - "Supabase credentials are optional for build, but write flows need a migrated project"
+    - "Do not print local .env or service-role values while preparing QA evidence"
+
+  steps:
+    - "npm install"
+    - "npm run dev -- -p 3010"
+    - "npm test"
+    - "Capture browser evidence under qa/screenshots and qa/browser-evidence.json"
+
+testing:
+  e2e_framework: "Playwright"
+  base_url: "http://localhost:3010"
+  timeout: 300000
+  plan: "../../QA_TEST_PLAN.md"
+  evidence: "../../QA_EVIDENCE.md"
+  routes:
+    - "/"
+    - "/book"
+    - "/book/requested?bookingCode=QA-123&paymentId=00000000-0000-4000-8000-000000000000"
+    - "/book/payments/00000000-0000-4000-8000-000000000000"
+    - "/owner#overview"
+    - "/owner/reports"
+    - "/owner#calendar"
+    - "/owner#orders"
+    - "/owner#vehicles"
+    - "/owner#customers"
+    - "/owner#create-booking"
+    - "/owner#documents"
+    - "/owner#income-expense"
+    - "/owner#tracking"

package/spec/roles.yaml

@@ -0,0 +1,30 @@
+roles:
+  - name: public_customer
+    description: Rental customer accesses the marketing flow, views vehicles, submits a booking request, and views deposit payment instructions.
+    permissions:
+      - "public_booking:read"
+      - "booking_request:create"
+      - "payment_instruction:read"
+
+  - name: owner
+    description: Owner or operations staff manages customers, vehicles, bookings, documents, income and expenses, and tracking.
+    permissions:
+      - "owner_dashboard:read"
+      - "customers:*"
+      - "vehicles:*"
+      - "bookings:*"
+      - "documents:*"
+      - "finance:read"
+      - "tracking:read"
+
+  - name: system_webhook
+    description: Provider webhook caller for payment and OM/GPS tracking callbacks.
+    permissions:
+      - "payments:webhook"
+      - "tracking:webhook"
+
+  - name: user
+    description: Aegis-authenticated Bugmole dashboard user with active workspace and project membership. Signs in through the dashboard OAuth session, views project-scoped QA surfaces, manages their own API keys, opens resource management pages, and views Aegis profile settings.
+    permissions:
+      - "projects:read"
+      - "keys:write"

package/spec/schema.md

@@ -0,0 +1,394 @@
+# Spec Schema Reference — Bugmole MCP
+
+This document defines the **schemas and conventions** for files under `/spec`.
+It is the contract between:
+
+- the **planning layer** (journey discovery + plan authoring), and
+- the **execution layer** (Playwright wrapper + evidence).
+
+---
+
+## 1) Global conventions
+
+### 1.1 Versioning
+
+Every spec file MUST include:
+
+- `version: <integer>` (or `"version": <integer>` for JSON)
+
+Increment `version` when:
+
+- a breaking schema change happens, or
+- semantics of a field changes.
+
+### 1.2 IDs
+
+IDs MUST be:
+
+- lowercase
+- words separated by `_` or `.`
+- stable and never reused for different meanings
+
+Examples:
+
+- `manager`
+- `order.take_payment`
+- `pos.core`
+- `missing_warehouse_blocks_staff`
+
+### 1.3 Evidence and Ground Truth
+
+A step is **PASS** only if it produces the required **Proof Tokens**:
+
+- DOM
+- Navigation
+- Network
+- State
+
+If proofs are missing, the result is **UNKNOWN** (treated as failure until fixed).
+
+### 1.4 Watermarks / safety
+
+Any entity created/modified by automation MUST be tagged with:
+
+`E2E::<date>::<runId>`
+
+Automation may ONLY modify/delete entities that contain the watermark tag.
+
+---
+
+## 2) `spec/roles.yaml`
+
+Defines roles (actors) and what they are allowed to do.
+
+### Schema
+
+```yaml
+version: 1
+description: string
+
+roles:
+  - id: string # unique role ID, e.g., "staff"
+    name: string # display name
+    description: string
+    inherits: string[] # optional; list of role IDs
+    capabilities: string[] # list of capability IDs
+
+capability_groups: # optional convenience grouping
+  <group_name>: string[]
+```
+
+**Notes**
+
+- capabilities are referenced by plans under `capabilities_required`.
+- `inherits` means effective capabilities = self + inherited.
+
+---
+
+## 3) `spec/domain_rules.yaml`
+
+Defines business prerequisites + invariants to generate negative variants and verify system correctness.
+
+### Schema
+
+```yaml
+version: 1
+description: string
+
+entities:
+  - id: string
+    description: string
+
+prerequisites:
+  - id: string
+    name: string
+    applies_to:
+      - action: string # e.g., "order.add_item"
+    requires:
+      - entity: string # one of entities[].id
+    notes: string
+
+policies:
+  - id: string
+    name: string
+    cases:
+      - when: string
+        staff_behavior: string | null
+        manager_behavior: string | null
+        default_behavior: string | null
+        message: string | null
+        requires_audit_log: boolean | null
+        allowed_fallbacks: string[] | null
+
+invariants:
+  - id: string
+    name: string
+    applies_to:
+      - action: string
+    requires: # optional gate
+      - policy: string | null
+    must_hold: string[] # human-readable invariant rules
+
+watermarks:
+  description: string
+  tag_format: string
+  scope_rules: string[]
+```
+
+**Notes**
+
+- `must_hold` is human-readable; the executor can map to proofs and/or API checks.
+- `policies` define expected behavior when prerequisites fail (block vs warn vs override).
+
+---
+
+## 4) `spec/blockers.yaml`
+
+Defines "surprise UI" (dialogs, toasts, overlays) and how to handle them.
+
+### Schema
+
+```yaml
+version: 1
+description: string
+
+blockers:
+  - id: string
+    type: modal | overlay | auth | banner | unknown
+    severity: auto_dismiss_safe | auto_wait_safe | auto_retry_safe | escalate_plan_update | hard_stop
+    detect:
+      any:
+        - selector: string | null
+        - text: string | null
+    resolve:
+      steps:
+        - try_click:
+            any: string[] # selectors or text match directives
+        - wait_until_gone:
+            timeout_ms: number
+        - wait_ms: number
+        - capture_evidence: boolean
+        - attempt_relogin: boolean
+        - hard_stop: boolean
+        - if_still_present: { wait_ms: number }
+
+hard_stop_conditions:
+  - id: string
+    description: string
+    detect:
+      any:
+        - selector: string | null
+        - text: string | null
+    action: hard_stop
+```
+
+**Notes**
+
+- `detect.any` is OR logic: if any detection matches, blocker is active.
+- `severity` controls whether the run continues or escalates.
+
+---
+
+## 5) `spec/journeys.graph.json`
+
+The living representation of the app as experienced by end-users.
+
+### Schema
+
+```json
+{
+  "version": 1,
+  "description": "string",
+  "nodes": [
+    {
+      "id": "string",
+      "signature": "string",
+      "title": "string",
+      "tags": ["string"],
+      "metadata": {}
+    }
+  ],
+  "edges": [
+    {
+      "id": "string",
+      "from": "node_id",
+      "to": "node_id",
+      "actor": "role_id",
+      "action": "string",
+      "params": {},
+      "proof_requirements": [{ "type": "dom|navigation|network|state", "expects": "string" }],
+      "notes": "string",
+      "risk": "low|med|high"
+    }
+  ],
+  "metadata": {
+    "screen_signature_spec": ["string"],
+    "edge_proof_token_minimums": {
+      "default": 1,
+      "commit_action": 2
+    }
+  }
+}
+```
+
+**Notes**
+
+- Nodes represent screens/states; edges represent action triggers.
+- Graph is updated by Explorer and used by Planner to generate plans.
+- A canonical flow is the source of truth for its steps, test cases, parity, and bug reports.
+- Only a flow with `stability: stable` and `linkedToGraph: true` participates in the larger app graph.
+- Flow revisions return to `stabilizing` when edited; reused steps reference the source canonical flow instead of being duplicated.
+
+---
+
+## 6) `spec/plans/*.flow.yaml`
+
+Human-readable plans that become executable journeys.
+
+### Schema
+
+```yaml
+version: 1
+id: string
+name: string
+description: string
+driver: string # optional registered app-driver; defaults to the configured driver
+platform: web | android | ios
+target: # optional driver target
+  base_url: string | null
+  app_id: string | null
+  device_id: string | null
+  serial: string | null
+flow: string | null # driver flow file or generated flow reference
+recovery: # optional bounded recovery policy
+  enabled: boolean
+  max_attempts: number
+  timeout_ms: number
+
+suites:
+  - id: string
+    runs: daily | weekly | on_demand | pr | release_candidate
+    journeys:
+      - id: string
+        actor: string # role id from roles.yaml
+        goal: string
+        capabilities_required: string[] # capability IDs
+        preconditions: string[] # human-readable checks
+        steps:
+          - action: string # e.g., "order.add_item"
+            params: # optional
+              any_key: any_value
+            expected_outcome: pass | blocked | warn | fail | unknown
+            proofs:
+              - type: dom | navigation | network | state
+                expects: string
+        variants: # optional
+          - id: string
+            actor: string | null
+            preconditions: string[]
+            steps: [...]
+```
+
+**Notes**
+
+- `expected_outcome` defaults to `pass` if omitted.
+- Negative cases use `blocked` or `warn` and still require proofs (e.g., error message visible).
+
+---
+
+## 7) `spec/bugs.index.json`
+
+Normalized bug backlog for linking to journeys and generating regression assertions.
+
+### Schema
+
+```json
+{
+  "version": 1,
+  "description": "string",
+  "bugs": [
+    {
+      "id": "string",
+      "title": "string",
+      "severity": "P0|P1|P2|P3",
+      "status": "open|closed|wontfix|duplicate",
+      "actor": "role_id",
+      "screen_signature": "string",
+      "action": "string",
+      "expected": "string",
+      "actual": "string",
+      "repro_steps": ["string"],
+      "regression_assertions": [{ "type": "dom|navigation|network|state", "expects": "string" }],
+      "links": {
+        "tracker": "string",
+        "evidence": ["string"]
+      }
+    }
+  ]
+}
+```
+
+**Notes**
+
+- `screen_signature` should match journey graph signatures.
+- `regression_assertions` are merged into relevant plans.
+
+---
+
+## 8) Proof Token "expects" conventions (recommended)
+
+To avoid ambiguity, standardize `expects` strings:
+
+### DOM proof examples
+
+- `visible:[data-testid='cart-line-item'][text~='Coffee']`
+- `text:[data-testid='payment-status'] == 'PAID'`
+- `count:[data-testid='cart-line-item'] >= 1`
+- `enabled:[data-testid='order-submit'] == true`
+
+### Navigation proof examples
+
+- `screen:order`
+- `url:/pos/order`
+- `signature:pos.order@route:/pos/order@root:screen-order`
+
+### Network proof examples
+
+- `POST /api/orders status 200`
+- `POST /api/payments status 200`
+
+### State proof examples
+
+- `order_id present`
+- `receipt_number present`
+- `inventory_delta(material='beans') == -10`
+
+---
+
+## 9) Suggested directory layout
+
+```
+spec/
+  roles.yaml
+  domain_rules.yaml
+  blockers.yaml
+  journeys.graph.json
+  app-ui-audit.schema.json
+  ui-parity-audit.schema.json
+  plans/
+    pos.core.flow.yaml
+  bugs.index.json
+docs/
+  plans/
+    SAD.md
+```
+
+---
+
+## 10) Change control
+
+- Plans and schemas should be reviewed like code.
+- Any automated update must produce:
+  - diff summary
+  - evidence links (trace/video/screenshot/network receipts)
+  - risk classification (low/med/high)

package/spec/test-case-results.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://app.bugmole.com/schemas/test-case-results.schema.json",
+  "title": "Bugmole Test Case Results",
+  "description": "What a run actually observed for the assumptions in one case set. Assumptions say what should be true; results say what happened. A result is the only thing that moves a case off \"planned\" on the dashboard, so every entry must name a case that exists in that set and say what was observed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "caseSetId",
+    "results"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "caseSetId": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9._-]+$",
+      "description": "The case set these verdicts judge, as written by bugmole_write_test_cases."
+    },
+    "journeyRevision": {
+      "type": "integer",
+      "description": "The journey revision the run judged. Assumptions are rewritten as a journey changes, so results recorded against an older revision are discarded rather than shown as proof of the current one."
+    },
+    "runId": {
+      "type": "string",
+      "description": "The run that produced these verdicts, when there is one."
+    },
+    "recordedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "results": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["caseId", "status", "detail"],
+        "properties": {
+          "caseId": {
+            "type": "string",
+            "description": "Must be a caseId present in the referenced case set."
+          },
+          "status": {
+            "enum": ["passed", "failed", "blocked", "needs_setup"],
+            "description": "\"failed\" means the check ran and the expectation did not hold. \"blocked\" means it could not be run at all. Do not use one for the other: a regression hidden behind a setup problem is how a broken app looks healthy."
+          },
+          "detail": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What was actually observed — the status code, the element that was or was not there, the assertion that failed. Required, including for a pass: a verdict nobody can review is not evidence."
+          },
+          "evidence": {
+            "type": "string",
+            "description": "Artifact key for the screenshot or capture backing this verdict."
+          }
+        }
+      }
+    }
+  }
+}

package/spec/test-cases.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://app.bugmole.com/schemas/test-cases.schema.json",
+  "title": "Bugmole Test Case Assumptions",
+  "description": "Candidate test cases derived from a discovered journey. These are assumptions: what the agent believes each step should do, grounded in nodes and edges that actually exist in the journey graph. They are not yet verified — a run is what turns an assumption into evidence.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "caseSetId",
+    "journeyId",
+    "journeyRevision",
+    "cases"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "caseSetId": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9._-]+$"
+    },
+    "projectId": { "type": "string" },
+    "journeyId": { "type": "string", "minLength": 1 },
+    "journeyRevision": { "type": "integer", "minimum": 1 },
+    "actor": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["caseId", "title", "nodeId", "intent", "steps", "expected", "confidence"],
+        "properties": {
+          "caseId": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[a-zA-Z0-9._-]+$"
+          },
+          "title": { "type": "string", "minLength": 1 },
+          "nodeId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Must be a node in the referenced journey at that revision."
+          },
+          "edgeId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional; when present must be an edge in the referenced journey."
+          },
+          "route": { "type": "string" },
+          "intent": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What this case is trying to prove, in one sentence."
+          },
+          "steps": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expected": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 },
+            "description": "Observable outcomes. Each should be checkable, not a restatement of the step."
+          },
+          "confidence": {
+            "enum": ["high", "medium", "low"],
+            "description": "How sure the agent is that this expectation is correct rather than guessed."
+          },
+          "basis": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "description": "What this assumption was derived from — source paths, observed controls, domain rules. An assumption with no basis should be low confidence."
+          },
+          "blockedReason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Set when the case cannot be asserted yet; recorded rather than silently dropped."
+          }
+        }
+      }
+    }
+  }
+}