@bugmole/cli 0.5.0 → 0.6.0

package/spec/domain_rules.yaml

@@ -22,3 +22,142 @@ domain_rules:
   - name: screenshot_evidence_manifest
     description: Browser evidence is manifest-backed.
     rule: "Screenshots live under qa/screenshots and the current manifest lives at qa/browser-evidence.json."
+
+  - name: agent_task_approval_mode
+    description: Each project has an approval mode for agent tasks, default auto.
+    rule: "manual holds every task until a project manager approves it; auto starts discovery and investigation tasks by themselves and holds code and ui tasks; extreme holds nothing. A task records approvedAt and approvedBy (a person, or auto:<mode>)."
+
+  - name: workers_take_only_approved_tasks
+    description: Nothing runs before it is approved.
+    rule: "Claiming a task and dispatching it to Bugmole Cloud both require approvedAt; claiming an unapproved task answers 409 'Task is waiting for approval'. Approving a cloud task hands it to a runner."
+
+  - name: worker_approval_is_stricter_never_looser
+    description: A worker can demand more approval than its project, never less.
+    rule: "With bugmole serve --approval <mode> (BUGMOLE_APPROVAL), a worker skips tasks its own mode would hold unless a person approved them; it never takes a task the project holds."
+
+  - name: test_case_revisions
+    description: A test case is never edited in place.
+    rule: "Changing a test case adds its next revision and marks the replaced one obsolete (status obsolete, supersededBy, obsoleteReason revised); retiring marks the current one obsolete (obsoleteReason retired). At most one revision of a caseId is active. Obsolete revisions don't run or count toward coverage and keep their results; a result records caseRevision, so a new revision is untested until a run judges it."
+
+  - name: test_case_proposals
+    description: Changes to test cases arrive as proposals.
+    rule: "Agents (bugmole_propose_test_case), developers (bugmole propose) and dashboard users propose add, change or retire with a summary and the revision they change. The approval mode decides acceptance: a project manager in manual and auto, on arrival in extreme. A proposal whose base revision is no longer current becomes outdated instead of overwriting. Bugmole storage is updated by the registry on accept; a project's own storage by bugmole serve or the proposing CLI."
+
+  - name: test_case_results_history
+    description: Recording test case results keeps the earlier ones.
+    rule: "Every result write (bugmole_write_test_case_results or a run's verdicts) replaces projects/<id>/test-case-results/<caseSetId>.json and also writes projects/<id>/test-case-history/<caseSetId>/<recordedAt>-<runId>.json. The dashboard reads the newest ten history files per case set; a case's history counts only verdicts for its own revision and the current journey revision. Blocked and needs_setup are neither passes nor failures; a case is flaky when it both passed and failed in that window."
+
+  - name: resume_never_strands_a_task
+    description: Resuming a task puts it where something will run it, or says why it can't.
+    rule: "POST /api/tasks/<id>/resume hands a cloud task (executionMode cloud) to the dispatcher. A task with executionMode self on a project that runs in the cloud (storage_mode managed or default_execution_mode cloud) is refused with 409 code needs_local_worker unless a machine's API key listed the project's tasks within LOCAL_WORKER_FRESH_MS (projects.local_worker_seen_at); canRunInCloud says a discovery can be resumed with executionMode cloud, which passes the same checks as starting on Bugmole Cloud."
+
+  - name: resume_keeps_approval_semantics
+    description: Resuming never skips the approval step the project requires.
+    rule: "A person's approval (approvedBy not auto:) survives a resume; an automatic or missing one is decided again by the project's current approval mode, and a task that waits for approval again is not dispatched until approved."
+
+  - name: completion_review_follows_approval_mode
+    description: A finished AI task waits for a person when the project's approval mode asks for it.
+    rule: "When a worker reports completed, the registry sets status in_review instead when the project's approval mode would hold that task type: manual reviews every task, auto reviews code and ui tasks, extreme none (completionStatus in src/registry/task-scheduling.ts). The response carries inReview: true and a message. A task in review is not claimable or resumable, a repeated completed is a no-op, and any other worker update answers 409. Tasks that were completed before review existed stay completed."
+
+  - name: only_a_person_reviews
+    description: Accepting or sending back a task is a person's call.
+    rule: "POST /api/tasks/<id>/accept (status completed, completed_at, reviewed_by, reviewed_at, optional review_note) and /send-back (a note is required; status queued, attempts 0, lease and worker cleared, review_note kept, approval kept) need project.manage and refuse API keys and runners with 403, so an agent cannot accept its own work. Both are audited (task.review_accepted, task.review_sent_back). The pipeline pauses while any task is in review."
+
+  - name: roles_are_suggested_then_confirmed
+    description: Bugmole suggests roles; a person decides which are used.
+    rule: "project_roles rows are suggested, confirmed or rejected, with source (sign_in_wall, role_gated_route, role_gated_menu, spec, persona, agent, person) and evidence. Anyone with project.write may suggest (evidence required); a person with project.manage adding a role confirms it. Only a person with project.manage confirms, renames, rejects or deletes; API keys and runners get 403. Suggesting a role a person already decided on changes nothing. Every change is audited (role.suggested, role.created, role.confirmed, role.rejected, role.updated, role.deleted)."
+
+  - name: only_confirmed_roles_are_planned
+    description: Plans and test case sets are written for confirmed roles only.
+    rule: "bugmole_plan and bugmole_write_test_cases refuse an actor that is not confirmed, naming the confirmed roles. A roles.yaml entry without status is confirmed; the registry's decision overrides roles.yaml. bugmole_write_spec writes any role an agent adds or promotes in roles.yaml as status suggested (a rejected one stays rejected). The pipeline pauses while a flow's only missing actors are suggested roles."
+
+  - name: project_secrets_are_write_only
+    description: Sign-in secrets for cloud runs are stored per project and never read back.
+    rule: "Project managers (project.manage) set, replace and delete project secrets in the dashboard; API keys and runners cannot write them. No route returns a value to a browser or an API key: the list carries name, environmentId, createdBy, updatedBy, createdAt, updatedAt and lastUsedAt only. Set, replace, delete and release are audited with names, never values."
+
+  - name: project_secrets_encryption
+    description: Values are encrypted per project and bound to where they belong.
+    rule: "Values are AES-256-GCM ciphertext under a per-project key derived with HKDF-SHA256 from the registry secret PROJECT_SECRETS_KEY (info bugmole:project-secret:<projectId>), with additional data <projectId>|<environmentId>|<name> and a key_version for rotation. Without PROJECT_SECRETS_KEY the secrets routes answer 503 and nothing is stored."
+
+  - name: project_secrets_released_only_to_cloud_runner
+    description: Only a Bugmole Cloud runner reads values, for the job it holds.
+    rule: "GET /api/runner/runs/:id/secrets and /api/runner/tasks/:id/secrets answer only the run token of that job, while the job is running on cloud:<id>. Project-wide values are replaced by the run environment's own values; explorations get project-wide values. Self-hosted workers never receive stored values and keep reading BUGMOLE_FLOW_SECRET_<NAME> from their own environment."
+
+  - name: runner_secrets_are_redacted
+    description: A secret value never leaves a worker in a log, result or report.
+    rule: "Every secret a worker types or is released is replaced with [secret] in logs, step results, failure context, manifests, text uploads and registry updates. A flow that types a secret records no Playwright trace. A cloud runner holds released values in its environment as BUGMOLE_FLOW_SECRET_<NAME> only while the job runs."
+
+  - name: cloud_exploration_signs_in_first
+    description: A project's sign-in flow runs before cloud exploration.
+    rule: "When a project has a sign-in flow, cloud exploration runs it first and explores in its session; the flow references secrets by name and saving a flow that contains a stored secret's value is refused. A flow that uses a secret the project doesn't have fails the exploration with a message naming the missing secret."
+
+  - name: coverage_counts_only_checked_work
+    description: Covered means a run checked it and it passed; everything else is listed as a gap.
+    rule: "A test case is an assumption until a run records a result for its current revision, and an assumption never counts as covered. Overview lists what isn't covered from data the dashboard already loads (apps/qa/src/lib/coverage-gaps.ts): pages or journeys with no test or case, journeys whose cases are all obsolete, tests never run, tests or cases whose latest result failed or was blocked, and what the last exploration couldn't reach (a sign-in wall, pages it couldn't open, links it skipped, its page limit). Each gap names its reason and a next action; a gap is listed only when a record shows it."
+
+  - name: estimates_before_starting
+    description: Starting a run or exploration says how long it usually takes, or that there is no estimate yet.
+    rule: "Before a test run starts, the estimate is the median of that test's last ten finished runs; without one it is estimated from the test's step count, then from other tests in the project; with none of these it says there is no estimate yet. Explorations use earlier ones of the same kind, or a first-time default. Estimates come from apps/qa/src/lib/eta.ts and are never shown as a promise."
+
+  - name: jira_credentials_are_write_only
+    description: A project's Jira API token and webhook secret are stored sealed and never read back.
+    rule: "Only project managers (project.manage) signed in to the dashboard connect, update, pause and disconnect Jira (PUT/DELETE /api/projects/:id/jira); API keys and runners cannot. The token is verified against Jira (myself and the project) before anything is stored, then sealed with AES-256-GCM under a key derived by HKDF-SHA256 from PROJECT_SECRETS_KEY with info bugmole:jira:<projectId> and additional data <projectId>|jira|<connectionId>|<field>. No response, audit entry or log line contains the token or webhook secret; the webhook secret is returned once, at connect or rotation. The site must be https://<name>.atlassian.net."
+
+  - name: jira_plan_and_tickets
+    description: Bugmole proposes its test plan as one Jira issue and keeps one ticket per approved test case.
+    rule: "POST /api/projects/:id/jira/plan creates one Task labelled bugmole-plan from the project's pending test case proposals (the same pending set is not posted twice); when every proposal on it is decided in Bugmole, the issue gets a comment and moves to a Done-category status. Accepted proposals (and, on request for Bugmole storage, existing active cases) get one Task each labelled bugmole-test plus a per-case label bugmole-case-<sha256(projectId|caseSetId|caseId)[0:16]>; jira_issue_links maps (project_id, case_set_id, case_id) to the issue key and revision. Creation is claimed per case and searches Jira by the case label first, so a lost write never creates a second ticket."
+
+  - name: jira_results_move_tickets
+    description: Run results move tickets to Done or Blocked and mention the people on failed ones.
+    rule: "When a run of a project with linked tickets ends, the outbox reports it once (jira-report:<runId>). Case verdicts come from the run's test-case-results record (latest or history) on Bugmole storage; a case-scoped retest without readable verdicts is judged by the run's own status. Passed moves the ticket to a Done-category transition and removes bugmole-blocked; failed or blocked moves it to a status named Blocked, or adds bugmole-blocked when the workflow has none, and comments with ADF mentions of the assignee and reporter (never Bugmole's own account) and the run's evidence link; needs_setup only comments."
+
+  - name: jira_mention_retests_one_case
+    description: Mentioning Bugmole on a ticket retests only that ticket's case.
+    rule: "POST /api/jira/webhook?connection=<id> accepts a delivery only with the connection's secret, compared in constant time, as X-Hub-Signature sha256 HMAC of the body, an X-Bugmole-Webhook-Secret header, or a token query parameter; accepted and rejected deliveries are audited with actor webhook jira:<connectionId>. A comment_created event on a linked ticket in the connected project, not written by Bugmole's own account, that contains the mention keyword or mentions Bugmole's account queues a run of the case's journey plan with idempotency key jira:<connectionId>:<issueKey>:<commentId>, trigger_source jira and runs.case_scope_json {caseSetId, caseIds:[caseId], jiraIssueKey}. Workers judge only scoped cases and merge them into the latest results, so other cases and tickets keep their state."
+
+  - name: plan_limits_on_every_way_in
+    description: Project and Free-workspace limits apply however a project is created, including CLI device pairing.
+    rule: "POST /api/projects/register (dashboard or API key) and CLI device pairing (POST /api/device-authorizations/claim) refuse a new project past the plan's project limit with 402 plan_limit, carrying suggestedPlan (the smallest plan with room), upgradeUrl (/billing?workspace=<id>&plan=<plan>) and billingUrl (absolute, from DASHBOARD_URL). Pairing never creates a second Free workspace: when the person already owns one, the project goes there, under that workspace's limit. A refused pairing is stored on the attempt (status refused, refusal_json) and returned by the CLI's poll, so `bugmole init` prints the message and the billing link instead of failing. Re-pairing an existing project is not a new project; pairing to a project the person does not manage is refused with 409 project_exists."
+
+  - name: keep_plan_before_period_end
+    description: A cancellation or scheduled plan change can be undone until the paid period ends.
+    rule: "POST /api/workspaces/:id/billing/resume (billing.manage, audited) clears cancel_at_period_end and any scheduled change while the provider's subscription is still live, activating it first when PayPal only suspended it. Cancelling at PayPal is final (a CANCELLED subscription cannot be activated), so otherwise it answers checkout_required and starts a checkout for the same plan and interval beginning at the period end, so nothing is charged twice. After the period ends it is refused with period_ended."
+
+  - name: choose_projects_within_limit
+    description: Projects past the plan's limit are read-only, and an owner chooses which stay active.
+    rule: "applyProjectLimit keeps projects with kept_at first, then the oldest, and locks the rest (locked_at); nothing is deleted. PUT /api/workspaces/:id/projects/active (workspace.manage, audited as billing.projects_chosen) sets kept_at on at most the plan's limit of the workspace's own projects and re-applies the limit, so later plan changes keep the choice."
+
+  - name: history_cutoff_everywhere
+    description: Run history follows the plan wherever the dashboard reads it, and retention follows the entitlements rollout.
+    rule: "Once limits are enforced, finished runs older than the plan's historyDays are hidden from the runs list, from GET /api/runs/:id (404 history_expired) and from run evidence under projects/<id>/runs/<runId>/ in the artifacts list and object routes (evidence of an unknown run is judged by its upload time). The daily retention job deletes the same runs and evidence only when FEATURE_ENTITLEMENTS enforces; in shadow or off it only logs how many it would delete."
+
+  - name: one_upsell_for_locked_features
+    description: Plan-gated features and limits show one upsell with the plan that includes them.
+    rule: "Dashboard pages render <LockedFeature feature enabled requiredPlan> (\"Available on Team and Business\", See plans -> /billing?workspace=&plan=) instead of their own copy, and a 402 plan_limit shows <PlanLimitNotice> with the suggested plan. Plan features reach it through one adapter (featureAccessFromUsage over GET /usage limits.features)."
+  - name: feature_access_single_evaluator
+    description: One function decides whether a workspace may use a feature, and the dashboard reads the same answer.
+    rule: "src/registry-worker/feature-access.ts effectiveFeatures evaluates every FEATURES entry in a fixed order and the first layer that decides wins: the global FEATURE_<NAME> kill switch (off or shadow → flag_off), beta rollout (FEATURE_<NAME>=beta needs a workspace_flags opt-in → beta_not_enabled), an unexpired workspace_feature_overrides row (→ workspace_override), then the plan-catalog features with the contract overrides on workspace_plans (→ plan or enterprise_override). Limits are entitlementsFor(plan, overrides), the same values enforcement reads. GET /api/workspaces/:id/features returns the evaluated features (enabled, reason, requiredPlan), limits (limit, used, unlimited) and plan to any workspace member; the dashboard hides features blocked by rollout or an operator and locks, with the required plan, those an upgrade unlocks."
+
+  - name: feature_flags_match_the_catalog
+    description: Every priced feature has exactly one flag.
+    rule: "FEATURE_DEFS in src/registry-worker/flags.ts maps each flag to at most one plan-catalog features key; every catalog features key has exactly one flag, and flags without one are listed in OPERATIONAL_FEATURES (entitlements, cloud_runners, billing, feedback, mcp). A test fails when either side drifts."
+
+  - name: platform_admin_routes
+    description: Only platform operators change overrides and contract plans, and every change is audited.
+    rule: "/api/platform/… routes require Authorization Bearer PLATFORM_ADMIN_TOKEN compared in constant time (SHA-256 of both sides); they answer 503 when the secret is unset and 401 for a missing or wrong token, and never accept dashboard sessions or API keys. The dashboard proxy never forwards them. Setting or clearing a feature override or beta opt-in, and setting a contract plan, writes an audit_log row with actor system:platform_admin, the x-bugmole-operator name, the new and previous values and the note. A contract plan is enterprise or free only, is refused with 409 while a provider subscription is active, re-applies the project limit and runs the plan-change hooks."
+
+  - name: one_app_one_project
+    description: A project is one app, identified by its domain or its repository and app folder; the same app in a workspace is the same project.
+    rule: "src/registry/project-identity.ts normalizes an identity: domain:<host> (lowercase, no port, no leading www., never a private or local host) for an app on the internet, repo:<host>/<path>#<appPath> for a git remote (scheme, user, password, token, port and .git dropped; lowercase host; path lowercased on github.com, gitlab.com, bitbucket.org, dev.azure.com and codeberg.org) plus the app's folder ('.' for the root). The CLI computes it (bugmole init, pairing, bugmole serve) and sends only the normalized, credential-free form; the registry normalizes again and stores projects.identity_kind, identity_key, identity_hash (SHA-256 of the key) and identity_origin, unique per workspace among undeleted projects. POST /api/projects/register with an identity (or a public appUrl) already in the workspace answers 200 {existing: true, project} instead of creating one; CLI pairing joins a project with the same identity in any workspace where the person is an owner, admin or member (poll returns its projectId, the key is scoped to it, the project and the person's role are unchanged). A project without an identity takes its first public environment base URL's domain. POST /api/projects/:id/identity sets it once; a different app is 409 identity_mismatch, one already in the workspace 409 identity_exists."
+
+  - name: monorepo_apps_are_separate_projects
+    description: Every app in a repository is its own project and counts toward the project limit.
+    rule: "The CLI finds web apps (framework dependencies, Django, Rails, Laravel, a static index.html) and mobile apps (Expo, React Native, Capacitor, Ionic, Flutter, Android com.android.application, iOS .xcodeproj/.xcworkspace), treating an npm/yarn/pnpm workspace, Turborepo, Nx or Lerna root as a container rather than an app. The app is the deepest one containing the working directory, the one named by --app-path, or the repository's only app; with several and no choice it sends no identity and asks for --app-path rather than collapsing apps into one project. With no web or mobile app it prints that data and AI projects are out of scope."
+
+  - name: free_identity_in_use
+    description: On Free, an app that already belongs to someone else's Free workspace can't be added to another Free workspace.
+    rule: "Creating a project (register, sign-up onboarding, CLI pairing) or giving one a domain through an environment in a Free workspace (no plan row, plan free, or a canceled plan) is refused with 409 identity_in_use when an undeleted, active (inactive_at IS NULL) project with the same identity_hash is in another Free workspace the person doesn't own. The message names the app, not the other workspace, and says to ask its owner for an invitation or upgrade (billingUrl for Team). Team, Business and Enterprise workspaces are never refused. It follows FEATURE_ENTITLEMENTS: enforced refuses, shadow logs, off allows. The one-Free-workspace-per-person rule is unchanged."
+
+  - name: inactive_projects_pause
+    description: Projects idle past the plan's inactiveProjectDays are paused until a member activates them.
+    rule: "inactiveProjectDays is a plan-catalog limit (Free 30, Team/Business/Enterprise null = never), on the pricing page as 'Projects paused after inactivity' and in GET /api/workspaces/:id/features limits. The daily job (jobs at 17 3 * * *, projects/inactivity.ts) takes a project's last activity as the latest of created_at, activated_at, local_worker_seen_at (a machine or MCP client with an API key listing tasks), runs requested/completed, agent tasks requested/heartbeat/completed, plan_drafts.updated_at, journey_revisions.created_at and non-system audit_log rows; past the limit it sets projects.inactive_at and audits project.paused. Enforced only when FEATURE_ENTITLEMENTS enforces; shadow logs what it would pause; off does nothing. A paused project is readable, refuses new runs, run claims, new tasks and task claims with 409 project_inactive {activateUrl}, and doesn't count toward the project limit, usage or Billing. POST /api/projects/:id/activate (project member with project.write, audited project.activated) clears inactive_at and sets activated_at, and answers 402 plan_limit when the workspace's active projects already fill the plan. The dashboard shows a Paused banner with Activate; bugmole serve prints the activation link."

package/spec/roles.yaml

@@ -28,3 +28,23 @@ roles:
     permissions:
       - "projects:read"
       - "keys:write"
+      - "proposals:create"
+
+  - name: project_manager
+    description: Workspace owner or admin (project.manage), always a person. Everything a user can do, plus approving agent tasks the project's approval mode holds back, accepting or sending back finished tasks it holds for review, confirming, renaming or rejecting suggested roles, changing the project's approval mode and where runs go, and setting the project's sign-in flow and write-only secrets for cloud runs (never reading a value back).
+    permissions:
+      - "projects:read"
+      - "keys:write"
+      - "tasks:approve"
+      - "tasks:review"
+      - "roles:decide"
+      - "proposals:decide"
+      - "project_settings:write"
+      - "project_secrets:write"
+
+  - name: worker
+    description: A bugmole serve process, coding-agent driver or Bugmole Cloud runner acting with a project API key or run token. Claims queued work and reports results; takes only approved agent tasks, and with --approval / BUGMOLE_APPROVAL only those its own mode would allow. Its completed may become in_review for a person, and it may suggest roles but never confirm one or review a task. Only a Bugmole Cloud runner, with the run token of the job it holds, reads the project's secret values (project_secrets:release); API-key workers never do.
+    permissions:
+      - "tasks:claim"
+      - "runs:claim"
+      - "roles:suggest"

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

@@ -11,7 +11,9 @@
     "results"
   ],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "schemaVersion": {
+      "const": 1
+    },
     "caseSetId": {
       "type": "string",
       "minLength": 1,
@@ -36,24 +38,38 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["caseId", "status", "detail"],
+        "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"],
+            "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."
+            "description": "What was actually observed \u2014 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."
+          },
+          "caseRevision": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "The revision of the case this verdict judged. A newer revision is untested until a run records a verdict for it."
           }
         }
       }

package/spec/test-cases.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "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 \u2014 a run is what turns an assumption into evidence.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -13,30 +13,88 @@
     "cases"
   ],
   "properties": {
-    "schemaVersion": { "const": 1 },
+    "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" },
+    "projectId": {
+      "type": "string"
+    },
+    "journeyId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "journeyRevision": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "actor": {
+      "type": "string"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "scenarioExclusions": {
+      "type": "array",
+      "description": "Scenario categories that don't apply, with the reason, instead of a silent gap (a step with no input has nothing to validate; an app with one role has no permission scenarios). Without nodeId an exclusion covers the whole journey.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "category",
+          "reason"
+        ],
+        "properties": {
+          "category": {
+            "enum": [
+              "happy_path",
+              "validation",
+              "error_state",
+              "permission",
+              "edge_case"
+            ]
+          },
+          "nodeId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Must be a node in the referenced journey."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
     "cases": {
       "type": "array",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["caseId", "title", "nodeId", "intent", "steps", "expected", "confidence"],
+        "required": [
+          "caseId",
+          "title",
+          "nodeId",
+          "intent",
+          "steps",
+          "expected",
+          "confidence"
+        ],
         "properties": {
           "caseId": {
             "type": "string",
             "minLength": 1,
             "pattern": "^[a-zA-Z0-9._-]+$"
           },
-          "title": { "type": "string", "minLength": 1 },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
           "nodeId": {
             "type": "string",
             "minLength": 1,
@@ -47,39 +105,96 @@
             "minLength": 1,
             "description": "Optional; when present must be an edge in the referenced journey."
           },
-          "route": { "type": "string" },
+          "route": {
+            "type": "string"
+          },
           "intent": {
             "type": "string",
             "minLength": 1,
             "description": "What this case is trying to prove, in one sentence."
           },
+          "category": {
+            "enum": [
+              "happy_path",
+              "validation",
+              "error_state",
+              "permission",
+              "edge_case"
+            ],
+            "description": "What kind of scenario this case is: happy_path (works for the intended user), validation (bad or missing input is rejected), error_state (backend failure, network error or no data is handled), permission (a user without access is kept out), edge_case (limits and unusual but valid input). Every step needs a happy_path case; each other category needs a case somewhere in the journey or a scenarioExclusions entry saying why it doesn't apply."
+          },
           "steps": {
             "type": "array",
             "minItems": 1,
-            "items": { "type": "string", "minLength": 1 }
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
           },
           "expected": {
             "type": "array",
             "minItems": 1,
-            "items": { "type": "string", "minLength": 1 },
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
             "description": "Observable outcomes. Each should be checkable, not a restatement of the step."
           },
           "confidence": {
-            "enum": ["high", "medium", "low"],
+            "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."
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "What this assumption was derived from \u2014 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."
+          },
+          "revision": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Which revision of this case this is; 1 when absent. A change never edits a case in place: it adds the next revision."
+          },
+          "status": {
+            "enum": [
+              "active",
+              "obsolete"
+            ],
+            "description": "Only the active revision runs and counts toward coverage; obsolete revisions are kept with their past results. Absent means active."
+          },
+          "supersededBy": {
+            "type": "integer",
+            "minimum": 2,
+            "description": "The revision that replaced this one (absent when the case was retired)."
+          },
+          "obsoletedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "obsoleteReason": {
+            "enum": [
+              "revised",
+              "retired"
+            ]
+          },
+          "proposalId": {
+            "type": "string",
+            "description": "The accepted proposal that created this revision."
           }
         }
-      }
+      },
+      "description": "A case may appear once per revision; at most one revision of a caseId is active."
     }
   }
 }

package/src/billing/plan-catalog.test.ts

@@ -2,7 +2,20 @@ import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import test from "node:test";
 import { COPY_HEADER, catalogCopy, catalogSource } from "../../scripts/sync-plan-catalog.mjs";
-import { AI_CREDIT_COST, PLANS, entitlementsFor, formatUsd, includedQuantity, overageCents } from "./plan-catalog.js";
+import {
+  AI_CREDIT_COST,
+  PLANS,
+  PLAN_IDS,
+  PRICING_ROWS,
+  PRICING_UNLISTED,
+  catalogPricingKeys,
+  entitlementsFor,
+  formatUsd,
+  includedQuantity,
+  overageCents,
+  pricingCell,
+  pricingValue,
+} from "./plan-catalog.js";
 
 test("the dashboard's copy of the plan catalog matches the source", async () => {
   const [source, copy] = await Promise.all([readFile(catalogSource, "utf8"), readFile(catalogCopy, "utf8")]);
@@ -26,8 +39,11 @@ test("free usage stops at the allowance while paid plans can buy more", () => {
   assert.equal(overageCents(free, "device_minute"), null);
   const team = entitlementsFor("team");
   assert.equal(overageCents(team, "browser_minute"), 4);
-  assert.equal(overageCents(team, "device_minute"), 25);
+  assert.equal(overageCents(team, "device_minute"), null, "Team has no device clouds, so no real-device minutes");
   assert.equal(includedQuantity(team, "device_minute"), 0);
+  assert.equal(overageCents(entitlementsFor("business"), "device_minute"), 25);
+  assert.equal(overageCents(entitlementsFor("business"), "browser_minute"), 3);
+  assert.equal(overageCents(entitlementsFor("team", { features: { deviceClouds: true } }), "device_minute"), 25, "a contract that adds device clouds adds device minutes");
   assert.equal(includedQuantity(team, "ai_credit"), 1500);
 });
 
@@ -44,3 +60,67 @@ test("AI credit costs match the pricing page", () => {
   assert.equal(formatUsd(24_900), "$249");
   assert.equal(formatUsd(4), "$0.04");
 });
+
+test("real-device minutes are priced only where device clouds are included", () => {
+  for (const plan of Object.values(PLANS)) {
+    const priced = overageCents(entitlementsFor(plan.id), "device_minute") !== null;
+    assert.equal(priced, plan.features.deviceClouds, plan.id);
+  }
+});
+
+test("only Enterprise lists contract extras, and they are descriptive only", () => {
+  for (const id of ["free", "team", "business"] as const) {
+    assert.ok(Object.values(PLANS[id].extras).every((value) => value === false), id);
+  }
+  assert.ok(Object.values(PLANS.enterprise.extras).every((value) => value === true));
+  assert.equal("extras" in entitlementsFor("enterprise"), false, "entitlements never carry contract extras");
+});
+
+test("every plan includes the everyone-gets features", () => {
+  for (const plan of Object.values(PLANS)) {
+    for (const key of ["unlimitedUsers", "unlimitedLocalRuns", "desktopBrowsers", "emulatedMobile", "aiFailureAnalysis"] as const) {
+      assert.equal(plan.features[key], true, `${plan.id}.${key}`);
+    }
+  }
+});
+
+test("every pricing row names a real catalog key", () => {
+  for (const row of PRICING_ROWS) {
+    for (const plan of PLAN_IDS) assert.notEqual(pricingValue(plan, row.key), undefined, `${row.key} on ${plan}`);
+  }
+  assert.equal(pricingValue("team", "features.notAThing"), undefined);
+  assert.equal(pricingValue("team", "limits.seats"), undefined);
+  assert.equal(new Set(PRICING_ROWS.map((row) => row.key)).size, PRICING_ROWS.length, "no duplicate rows");
+});
+
+test("every catalog feature, extra and limit is on the pricing page or deliberately unlisted", () => {
+  const shown = new Set<string>(PRICING_ROWS.map((row) => row.key));
+  for (const key of catalogPricingKeys()) {
+    assert.ok(shown.has(key) || PRICING_UNLISTED[key], `${key} is in the catalog but not on the pricing page`);
+    assert.ok(!(shown.has(key) && PRICING_UNLISTED[key]), `${key} is both shown and unlisted`);
+  }
+  for (const key of Object.keys(PRICING_UNLISTED)) assert.ok((catalogPricingKeys() as string[]).includes(key), `unlisted ${key} is not a catalog key`);
+});
+
+test("pricing cells follow the catalog", () => {
+  const row = (key: string) => PRICING_ROWS.find((item) => item.key === key)!;
+  assert.equal(pricingCell("team", row("features.teams")), "\u2713");
+  assert.equal(pricingCell("free", row("features.teams")), "\u2014");
+  assert.equal(pricingCell("team", row("overage.browser_minute")), "$0.04 / min");
+  assert.equal(pricingCell("business", row("overage.browser_minute")), "$0.03 / min");
+  assert.equal(pricingCell("team", row("overage.device_minute")), "\u2014");
+  assert.equal(pricingCell("business", row("overage.device_minute")), "$0.25 / min");
+  assert.equal(pricingCell("enterprise", row("overage.browser_minute")), "Volume pricing", "contract usage isn't shown at list rates");
+  assert.equal(pricingCell("team", row("limits.cloudMinutes")), "3,000");
+  assert.equal(pricingCell("enterprise", row("limits.projects")), "Custom");
+  assert.equal(pricingCell("business", row("limits.historyDays")), "90 days");
+  assert.equal(pricingCell("free", row("limits.inactiveProjectDays")), "30 days");
+  assert.equal(pricingCell("team", row("limits.inactiveProjectDays")), "Never", "no limit reads Never, not Custom");
+  assert.equal(pricingCell("enterprise", row("limits.inactiveProjectDays")), "Never");
+});
+
+test("only Free pauses inactive projects, and contracts can change it", () => {
+  assert.equal(entitlementsFor("free").inactiveProjectDays, 30);
+  for (const id of ["team", "business", "enterprise"] as const) assert.equal(entitlementsFor(id).inactiveProjectDays, null, id);
+  assert.equal(entitlementsFor("enterprise", { inactiveProjectDays: 90 }).inactiveProjectDays, 90);
+});