@minicor/mcp-server 4.3.0 → 4.5.0

package/skills/general/job-build-loop.md

@@ -1,8 +1,8 @@
 ---
 name: job-build-loop
-description: The Minicor test-case-first build/debug loop for Jobs. Jobs are the macroscope (test cases, step graph, executions); Dev Mode is the microscope (one workflow's internal flow steps). Prescriptive tool sequences for teaching, building drafts, running the green-gate, drilling failures top-down, step-range replays with seeded ctx, cooperative stop, and publishing. Use EVERY TIME you build or debug a Job.
+description: The Minicor test-case-first build/debug loop for Jobs. Jobs are the macroscope (test cases grouped into scenarios, step graph, executions); Dev Mode is the microscope (one workflow's internal flow steps). Prescriptive tool sequences for teaching, building drafts, running the green-gate, drilling failures top-down, step-range replays with seeded ctx, cooperative stop, and publishing. Use EVERY TIME you build or debug a Job.
 category: general
-tags: [jobs, testing, build-loop, debugging, test-cases, mandatory]
+tags: [jobs, testing, build-loop, debugging, test-cases, scenarios, mandatory]
 priority: 100
 ---
 
@@ -13,6 +13,14 @@ platform's Jobs UI (Overview = macroscope, Build = microscope) and is **test-cas
 the test cases ARE the definition of done. Never build a step graph before you can say what
 "green" means.
 
+Vocabulary: customers teach a job by sending **sample API calls** (JSON inputs). Samples
+group into **scenarios** — named buckets for the distinct paths/outcomes a job can take
+(happy path, a validation rejection, a not-found branch, ...). Scenarios are FIRST-CLASS:
+each sample is one test case, and its scenario is its `scenarioId` (manage scenarios with
+`list_scenarios` / `create_scenario` / `update_scenario` / `delete_scenario`). The legacy
+`scenario:<slug>` tag on cases is dual-written as a compatibility layer — a scenarioId
+write rewrites the tag, and a tag-only write finds-or-creates the Scenario.
+
 ```
 teach / add_test_case          <- 1. green-gate first
   -> update_job variant=draft  <- 2. build the macroscope (step graph)
@@ -58,6 +66,22 @@ Before writing any definition:
 - Tighten or disable cases later with `update_test_case` (e.g. `enabled: false` instead of
   deleting history).
 
+**Group cases into scenarios as you go.** Each case is one sample input; its scenario is the
+path/outcome it exercises. Set it via the `scenarioId` param on `add_test_case` /
+`update_test_case` (create with `create_scenario`, or find ids with `list_scenarios`).
+`teach_job` can't set it directly — after every test/teach run the service auto-groups
+ungrouped cases by the execution path they took (manual grouping is never overridden);
+rename auto-created scenarios with `update_scenario`, or move a case with
+`update_test_case scenarioId` (null ungroups):
+
+- Name the scenario after the path/outcome, not the input: `rejects-missing-last-name`,
+  `books-earliest-slot` — NOT `john-smith`.
+- All cases in a scenario share IDENTICAL assertions — the assertions are the scenario's
+  definition of its outcome. Add more samples to a scenario by adding more cases with the
+  same scenarioId + assertions. Ungrouped cases are treated as one-sample scenarios.
+- Compatibility: the legacy `scenario:<slug>` tag still works (it finds-or-creates the
+  Scenario) and is kept in sync on every scenarioId write — prefer scenarioId.
+
 A job with zero test cases is not buildable — there is no definition of correct.
 
 ## Step 2: Build the draft (macroscope)
@@ -77,7 +101,10 @@ run_tests(variant="draft")            # all enabled cases
 run_tests(variant="draft", testCaseIds=[...])   # a subset while iterating
 ```
 
-- Returns totals + per-case results, each linking a `jobExecutionId` for drill-down.
+- Returns totals + per-case results, each linking a `jobExecutionId` for drill-down —
+  plus a per-scenario `scenarios` grouping with prebuilt summaries
+  ("Refund Flow: 3/3 samples passed"). A scenario is green only when ALL of its sample
+  cases pass; ungrouped cases land in a trailing "Ungrouped" bucket.
 - Green -> Step 6 (publish). Red -> Step 4.
 
 ## Step 4: Drill failures top-down (macroscope)
@@ -158,6 +185,11 @@ runs, fixes through the executor).
 ## Anti-patterns
 
 - Building a definition before any test case exists (no green-gate).
+- Cases in one scenario with divergent assertions (a scenario has ONE definition of its
+  outcome — if two cases expect different outcomes, they are different scenarios).
+- Naming a scenario after its input instead of its path/outcome (`john-smith`).
+- Leaving auto-created scenarios named "Scenario N" — rename them (update_scenario) to
+  describe the behavior they capture.
 - Re-running the entire job to debug one mid-graph step (use fromStepId + seedExecutionId).
 - Using a range run WITHOUT `seedExecutionId` for a mid-graph start (ctx will be empty).
 - Editing a workflow's Dev Mode branch and re-running job tests without `dev_mode_publish`

package/skills/general/nestjs-middleware-to-job.md

@@ -1,6 +1,6 @@
 ---
 name: nestjs-middleware-to-job
-description: Turn an existing NestJS customer middleware endpoint (a controller that orchestrates Minicor workflows) into a Job — a structured JobDefinition step graph registered via register_job, with test cases as the green-gate. Use when migrating customers/middlewares/* controllers onto the Jobs layer.
+description: Turn an existing NestJS customer middleware endpoint (a controller that orchestrates Minicor workflows) into a Job — a structured JobDefinition step graph registered via register_job, with test cases (sample inputs tagged into scenarios) as the green-gate. Use when migrating customers/middlewares/* controllers onto the Jobs layer.
 category: task
 tags: [jobs, middleware, nestjs, migration, testing, register_job]
 priority: 80
@@ -66,13 +66,16 @@ the controller's `WORKFLOW_IDS` constants.
 4. Build the step graph per the table. Login/smart-launch → a `cache`d workflow step. Each
    downstream workflow → a workflow step with templated `input`. Munging → the `output` block.
 5. **Define the green-gate FIRST**: `add_test_case` with a representative (test-only) input and
-   assertions over the expected output, e.g. `output.web_agent_video_url != null`.
+   assertions over the expected output, e.g. `output.web_agent_video_url != null`. Tag each case
+   into a scenario (`scenario:<slug>`, named after the path/outcome — one per distinct path the
+   endpoint can take); cases in a scenario share identical assertions, one sample input each.
 6. `register_job(workspaceId, middlewareId, path, definition)` (create a router first with
    `create_router` if needed).
 7. `run_job` with the test input; inspect the JobExecution — each workflow step carries
    `workflowExecutionId` + `region` to deep-link the real Minicor run.
-8. **Green-gate**: `run_tests` until `green: true`. Drill into failures → job execution → step →
-   Minicor run; fix with `update_job` and re-run.
+8. **Green-gate**: `run_tests` until `green: true`. Read results per-scenario (group cases by
+   their `scenario:` tag; a scenario is green only when all its samples pass). Drill into
+   failures → job execution → step → Minicor run; fix with `update_job` and re-run.
 
 ## Rules