diff --git a/docs/agent/README.md b/docs/agent/README.md index efb17fb1..5b8dde8b 100644 --- a/docs/agent/README.md +++ b/docs/agent/README.md @@ -18,9 +18,9 @@ This directory supports repository-native AI coding agents. It is not a runtime Agent adapters should remain small and point back to the canonical contract rather than copying the full project description. -The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. +The nested `/maven-consumer-project/AGENTS.md` is a dependency-owned guidance bootstrap plus a short discover-vs-isolate pointer. It materializes version-matched guidance, directs the consumer agent to `.pickleball/AGENT-GUIDE.md`, and states that a diagnostic `mvn test` finds which scenarios fail while headless Workbench MCP (`mcp .`) isolates a known failure. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. -The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. +The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same bootstrap-plus-pointer for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation. It may point humans and agents at `AGENTS.md` for guidance export, but should not duplicate the AI guidance lifecycle. diff --git a/docs/agent/feature-map.md b/docs/agent/feature-map.md index 2537fd37..05efac3d 100644 --- a/docs/agent/feature-map.md +++ b/docs/agent/feature-map.md @@ -47,6 +47,6 @@ The canonical worker bootstrap environment is `PKB_CONTROL_BRIDGE_SESSION_DIR`, `WorkbenchLiveSession` binds operations to the controller-owned paused scenario and verifies worker PID, bridge runtime id, and scenario id stability. A `FAILED` `executeStep` result leaves that same paused worker available; it is not a worker-ending error. Step Override source is compiled and loaded worker-side. Normal live calls do not invoke Maven/Gradle, resynchronize, or restart the worker. -The lightweight non-Spring stdio MCP adapter and player-style Swing/WebView UI both delegate through `WorkbenchServices` / `WorkbenchController`. `LiveScenarioPlayer` is a Workbench-side headless presentation model for the editable session buffer, stable line identities, selection, click-to-seek playhead, and player state only; it does not parse or execute Pickleball steps, model ParsingMap/NodeMap semantics, or claim runtime rewind. `LiveEditorView` is the Text vs Blocks presentation choice for that same buffer; toggling it must not change document text, selection, or playhead id. While `RUNNING`, `WorkbenchController.executeStep` owns playhead follow once (`LivePlaybackCoordinator.followExecutedStep`); the Swing Play loop continues without remaking that mark, and leftover marks of an already-consumed step are no-ops. The controller also owns the watched-agent control lease (`HUMAN` / `AGENT`, banner `currentAction`, gated Save permission). Consumer AI agents use headless MCP (`mcp .`). UI mode may write a localhost attach endpoint to `.pickleball/workbench/attach.json` so a watcher can join a human GUI session instead of starting a second Workbench; that attach file is not the consumer-agent path for this release. The left-rail picker filters project-owned scenarios by name (starts with / contains / ends with / full match; default contains; case-insensitive) and Cucumber tags (include AND, exclude NOT, Feature/Rule/outline/Examples inheritance parsed from catalog `.feature` files without calling Cucumber). Feature-file selection is an optional collapsed secondary filter; with none selected, name/tag apply to every catalog scenario. The live editor is Gherkin text or a block WebView over that same player model. Global Play starts from the first executable step; Step Editor **Step** is isolated `executeStep`; **From Here** runs from the selected step; wait-at-end stays in play so Enter can append-and-continue. Mapping property types go through `mappingPut` / `mappingRestore`. Terminal tails existing worker log files. Diagnostic explorer reads retained `reports/diagnostic-runs` artifacts in the repository evidence order. The default buffer is a Workbench-owned browser demo against `URL.home`; **Save** is confirmation-gated and copies only a picker-loaded scenario back to its originating `.feature` file. OpenJFX is Workbench-only. MCP mode reserves stdout for newline-delimited MCP JSON-RPC and redirects ordinary output to stderr. The UI remains execution-oriented and does not recreate a project IDE, generic build/process UI, source navigator, or collaboration system. +The lightweight non-Spring stdio MCP adapter and player-style Swing/WebView UI both delegate through `WorkbenchServices` / `WorkbenchController`. `LiveScenarioPlayer` is a Workbench-side headless presentation model for the editable session buffer, stable line identities, selection, click-to-seek playhead, and player state only; it does not parse or execute Pickleball steps, model ParsingMap/NodeMap semantics, or claim runtime rewind. `LiveEditorView` is the Text vs Blocks presentation choice for that same buffer; toggling it must not change document text, selection, or playhead id. While `RUNNING`, `WorkbenchController.executeStep` owns playhead follow once (`LivePlaybackCoordinator.followExecutedStep`); the Swing Play loop continues without remaking that mark, and leftover marks of an already-consumed step are no-ops. The controller also owns the watched-agent control lease (`HUMAN` / `AGENT`, banner `currentAction`, gated Save permission). Consumer AI agents discover unknown or multi-scenario failures with a diagnostic `mvn test`, then isolate a known failure with headless MCP (`mcp .`); missing `workbench_*` tools means start that stdio server, not skip Workbench. UI mode may write a localhost attach endpoint to `.pickleball/workbench/attach.json` so a watcher can join a human GUI session instead of starting a second Workbench; that attach file is not the consumer-agent path for this release. The left-rail picker filters project-owned scenarios by name (starts with / contains / ends with / full match; default contains; case-insensitive) and Cucumber tags (include AND, exclude NOT, Feature/Rule/outline/Examples inheritance parsed from catalog `.feature` files without calling Cucumber). Feature-file selection is an optional collapsed secondary filter; with none selected, name/tag apply to every catalog scenario. The live editor is Gherkin text or a block WebView over that same player model. Global Play starts from the first executable step; Step Editor **Step** is isolated `executeStep`; **From Here** runs from the selected step; wait-at-end stays in play so Enter can append-and-continue. Mapping property types go through `mappingPut` / `mappingRestore`. Terminal tails existing worker log files. Diagnostic explorer reads retained `reports/diagnostic-runs` artifacts in the repository evidence order. The default buffer is a Workbench-owned browser demo against `URL.home`; **Save** is confirmation-gated and copies only a picker-loaded scenario back to its originating `.feature` file. OpenJFX is Workbench-only. MCP mode reserves stdout for newline-delimited MCP JSON-RPC and redirects ordinary output to stderr. The UI remains execution-oriented and does not recreate a project IDE, generic build/process UI, source navigator, or collaboration system. For this boundary, scenario validation is limited to the affected `@control-bridge` and/or `@step-override-bridge` tags with `pkb_parallel=80` where practical. Do not run `@all` for Workbench isolation changes. diff --git a/docs/consumer-agent-guide.md b/docs/consumer-agent-guide.md index 257ae6da..47f5ee81 100644 --- a/docs/consumer-agent-guide.md +++ b/docs/consumer-agent-guide.md @@ -6,12 +6,14 @@ A consumer project may contain only a short `AGENTS.md` bridge. That bridge can ## Tool chooser -Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`). Do not start the Workbench GUI. +Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`) to isolate a known failure. Do not start the Workbench GUI. -1. **Live headless MCP** — isolate a failing step in a paused worker. Reuse compilation, rewrite Gherkin in the live buffer, and inspect the page and semantic events in the same browser/Mapping state. -2. **One diagnostic `mvn test`** — after the live loop has isolated the failure, run one bounded confirmation with `pkb_runvars` so an evidence pack is retained. -3. **Emit the human handoff** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. -4. **Edit real consumer source** — change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. +1. **Discover** — when you do not yet know which scenarios fail, or you need many/parallel scenarios: run one diagnostic `mvn test` with `pkb_runvars` (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, the narrowest useful `pkb_tags`/`pkb_name`, and `pkb_parallel` when the project supports it). This is not a skip of Workbench; it is how you find failures. Do not start Workbench just to run the whole suite. +2. **Isolate / debug a known failing scenario** — use live headless Workbench MCP. If `workbench_*` MCP tools are not available in this session, start headless Workbench MCP first (`mcp .` via the documented Maven exec of `tools.dscode.launcher.PickleballWorkbenchLauncher`, `classpathScope=test`, args `mcp .`) and treat that as a required setup step — do not keep using `mvn test` for isolation/debug merely because MCP is disconnected. Prefer the IDE launching that command as an MCP stdio server (Copilot/Cursor MCP config) over a throwaway terminal you then ignore; stdio MCP only becomes tools if the IDE owns the process. After it is up: `workbench_sync` once, `workbench_worker_start`, `workbench_request_control`, then `workbench_execute_step` / `workbench_player_replace_document` / inspect. +3. **Confirm after isolation** — one bounded diagnostic `mvn test` with the existing AI defaults (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, narrowest useful `pkb_tags`/`pkb_name`). +4. **Emit the human handoff, then edit real consumer source** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. Change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. + +Missing `workbench_*` tools is a reason to start Workbench MCP, not a reason to skip it. A multi-scenario diagnostic test is a reason to run `mvn test` first, not a reason to skip Workbench afterward. Do not copy consumer features into `.pickleball` as a sandbox. @@ -19,8 +21,8 @@ Do not copy consumer features into `.pickleball` as a sandbox. From the consumer project, with Pickleball on the test classpath: -1. Start the launcher with `mcp .` (not a GUI command). -2. Call `workbench_sync` once. The synchronizer skips Maven/Gradle when Java/build/dependencies are unchanged, and refreshes test resources without a full `test-compile` when only features/config/data changed. +1. If `workbench_*` tools are not already in this session, start the launcher with `mcp .` (not a GUI command). Prefer the IDE owning that process as an MCP stdio server. +2. Call `workbench_sync` once. The agent must call it; Workbench does not auto-watch. Full compile when there is no live classpath or when Java/`pom`/dependencies changed; resources-only for feature/config/data; skip when unchanged. Live buffer edits need no sync. 3. `workbench_worker_start` — reuse the compiled live classpath; do not rebuild to start a worker. 4. `workbench_request_control` 5. Isolate with `workbench_execute_step` and/or `workbench_player_replace_document`. @@ -44,7 +46,7 @@ Worker restart without rebuild already exists (`workbench_worker_restart`). Step Keep first-read small. After a successful export: 1. Follow the consumer project's own instructions first; they remain authoritative for project-specific behavior. -2. Stay in this guide's tool chooser and live loop. +2. Stay in this guide's tool chooser: discover with a diagnostic `mvn test` when the failing scenario is unknown; isolate a known failure with the live headless MCP loop. 3. Inspect the **real** consumer `pom.xml`, Pickleball runner subclass, features, configuration, data, mappings, and test support before changing them. 4. Open a specific exported guide only when that topic is needed, for example `docs/dynamic-steps.md`, `docs/diagnostic-reporting.md`, `docs/configuration.md`, or `docs/ai-run-configuration.md`. 5. Do not assume the Pickleball core source repository is present. A normal consumer may only have the Maven dependency. diff --git a/docs/consumer-project.md b/docs/consumer-project.md index 35845161..996ae1a1 100644 --- a/docs/consumer-project.md +++ b/docs/consumer-project.md @@ -26,7 +26,7 @@ Rerun export before Pickleball work even when `.pickleball` already exists. A su Compatibility note: an older Pickleball release whose exporter predates the manifest lifecycle may leave newer files or a newer manifest behind after a downgrade. Those leftovers are not authoritative for the downgraded dependency; prefer the dependency actually resolved on the test classpath and the files freshly exported by that dependency. -AI agents should read `.pickleball/AGENT-GUIDE.md` first after a successful export. That guide's tool chooser is the agent path: headless Workbench MCP (`mcp .`), one bounded diagnostic `mvn test`, then edits to the real consumer source. Do not treat `.pickleball/maven-consumer-project/` as the project under test, and do not dump `docs/README.md` or the whole snapshot into first-read context. Human readers can start with `.pickleball/docs/README.md`; links from those guides to `maven-consumer-project` resolve to the exported version-matched reference files. +AI agents should read `.pickleball/AGENT-GUIDE.md` first after a successful export. That guide's tool chooser is the agent path: one diagnostic `mvn test` to discover which scenarios fail when that is still unknown; live headless Workbench MCP (`mcp .`) to isolate a known failure (start the stdio server if `workbench_*` tools are missing; do not skip Workbench because MCP is disconnected); one bounded diagnostic confirmation; then edits to the real consumer source. Do not treat `.pickleball/maven-consumer-project/` as the project under test, and do not dump `docs/README.md` or the whole snapshot into first-read context. Human readers can start with `.pickleball/docs/README.md`; links from those guides to `maven-consumer-project` resolve to the exported version-matched reference files. ## Version-matched reference snapshot diff --git a/docs/pickleball-workbench.md b/docs/pickleball-workbench.md index 632d190c..26ae2d4e 100644 --- a/docs/pickleball-workbench.md +++ b/docs/pickleball-workbench.md @@ -58,7 +58,7 @@ mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java \ mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.launcher.PickleballWorkbenchLauncher" "-Dexec.classpathScope=test" "-Dexec.args=mcp ." ``` -Humans who want the Swing player can pass `ui .` instead. With no launcher arguments, `ui` and the current directory are selected automatically for that human default. Other Workbench commands are forwarded in the same form, for example `"-Dexec.args=sync ."`. Agents for this release should not use the GUI, `ui .`, or `.pickleball/workbench/attach.json` as their path; see `.pickleball/AGENT-GUIDE.md`. +Humans who want the Swing player can pass `ui .` instead. With no launcher arguments, `ui` and the current directory are selected automatically for that human default. Other Workbench commands are forwarded in the same form, for example `"-Dexec.args=sync ."`. Consumer agents start `mcp .` when isolating a known failure. They may run a diagnostic `mvn test` first to discover which of several scenarios fail. Missing `workbench_*` tools means start this stdio server, not skip Workbench. Agents for this release should not use the GUI, `ui .`, or `.pickleball/workbench/attach.json` as their path; see `.pickleball/AGENT-GUIDE.md`. Gradle consumers can expose the same dependency-owned launcher without resolving a cache path or adding a Workbench dependency: @@ -321,7 +321,7 @@ Start the lightweight non-Spring MCP server for a consumer project. This is the java -jar $workbenchJar mcp ".\maven-consumer-project" ``` -Or, from a Maven consumer test classpath, `"-Dexec.args=mcp ."`. Do not document or use the Swing GUI as the agent path. +Or, from a Maven consumer test classpath, `"-Dexec.args=mcp ."`. Consumer agents start this stdio server when isolating a known failure. They may first run a diagnostic `mvn test` to discover which scenarios fail. Missing `workbench_*` tools means start this server (preferably as an IDE-owned MCP process), not skip Workbench. Do not document or use the Swing GUI, `ui .`, or `.pickleball/workbench/attach.json` as the agent path. The server uses the official Java MCP SDK core and stdio transport with the Jackson 2 JSON adapter. MCP dependencies are Workbench-only and are shaded into the executable companion. Workbench deliberately does not use Spring Boot, Spring Framework, Spring AI, WebMVC, or Tomcat. diff --git a/maven-consumer-project/.github/copilot-instructions.md b/maven-consumer-project/.github/copilot-instructions.md index e303a3a3..e2634ab6 100644 --- a/maven-consumer-project/.github/copilot-instructions.md +++ b/maven-consumer-project/.github/copilot-instructions.md @@ -1 +1,5 @@ Before any Pickleball work, run `mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.common.reporting.diagnostic.DiagnosticCli" "-Dexec.classpathScope=test" "-Dexec.args=export-guidance .pickleball"` and, after a successful export, follow `.pickleball/AGENT-GUIDE.md`. + +To find which of several scenarios fail, run one diagnostic `mvn test` with `pkb_runvars` (parallel is OK when the project supports it). That discovery run is not a skip of Workbench. + +To isolate or debug a known failure, start headless Workbench MCP (`mcp .`) if `workbench_*` tools are not already in this session. Do not skip Workbench because MCP is disconnected, and do not start the GUI. diff --git a/maven-consumer-project/AGENTS.md b/maven-consumer-project/AGENTS.md index e303a3a3..e2634ab6 100644 --- a/maven-consumer-project/AGENTS.md +++ b/maven-consumer-project/AGENTS.md @@ -1 +1,5 @@ Before any Pickleball work, run `mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.common.reporting.diagnostic.DiagnosticCli" "-Dexec.classpathScope=test" "-Dexec.args=export-guidance .pickleball"` and, after a successful export, follow `.pickleball/AGENT-GUIDE.md`. + +To find which of several scenarios fail, run one diagnostic `mvn test` with `pkb_runvars` (parallel is OK when the project supports it). That discovery run is not a skip of Workbench. + +To isolate or debug a known failure, start headless Workbench MCP (`mcp .`) if `workbench_*` tools are not already in this session. Do not skip Workbench because MCP is disconnected, and do not start the GUI. diff --git a/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java b/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java index 573c7865..6e822ae7 100644 --- a/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java +++ b/maven-consumer-project/src/test/java/tools/dscode/common/reporting/diagnostic/PickleballGuidanceChecks.java @@ -55,9 +55,18 @@ void dependencyPrintsCanonicalAgentGuide() { assertTrue(guide.contains("afterSequence")); assertTrue(guide.contains("docs/pickleball-workbench.md")); assertTrue(guide.contains("DiagnosticCli help")); + assertTrue(guide.contains("**Discover**")); + assertTrue(guide.contains("**Isolate / debug a known failing scenario**")); + assertTrue(guide.contains("Missing `workbench_*` tools is a reason to start Workbench MCP")); + assertTrue(guide.contains("not a reason to skip it")); + assertTrue(guide.contains("PickleballWorkbenchLauncher")); + assertTrue(guide.contains("does not auto-watch")); + assertTrue(guide.contains("pkb_parallel")); String chooser = guide.substring(0, guide.indexOf("Generated guidance lifecycle")); assertFalse(chooser.contains("attach.json")); assertFalse(chooser.contains("ui .")); + assertTrue(chooser.contains("This is not a skip of Workbench")); + assertTrue(chooser.contains("do not keep using `mvn test` for isolation/debug")); } @Test @@ -203,11 +212,15 @@ void dependencyExportsVersionMatchedGuidanceAndManifest() throws Exception { assertTrue(guide.contains("workbench_investigation_emit")); assertTrue(guide.contains("pkb_reportretention=failed")); assertTrue(guide.contains("Do not copy, modify, or execute files")); + assertTrue(guide.contains("Missing `workbench_*` tools is a reason to start Workbench MCP")); + assertTrue(guide.contains("PickleballWorkbenchLauncher")); String consumerProject = Files.readString(root.resolve("docs/consumer-project.md")); assertTrue(consumerProject.contains("keep console verbosity low")); assertTrue(consumerProject.contains("older Pickleball release whose exporter predates the manifest lifecycle")); assertTrue(consumerProject.contains("Version-matched reference snapshot")); + assertTrue(consumerProject.contains("discover which scenarios fail")); + assertTrue(consumerProject.contains("do not skip Workbench because MCP is disconnected")); } finally { deleteTree(root); } diff --git a/scripts/verify_agent_contract.py b/scripts/verify_agent_contract.py index 4ef92196..cee0e60e 100644 --- a/scripts/verify_agent_contract.py +++ b/scripts/verify_agent_contract.py @@ -295,33 +295,60 @@ def validate_consumer_bridge(errors: list[str]) -> None: text = path.read_text(encoding="utf-8").strip() texts.append(text) nonblank_lines = [line for line in text.splitlines() if line.strip()] - if len(nonblank_lines) != 1: + if not (3 <= len(nonblank_lines) <= 8): errors.append( - "Consumer guidance bridge must stay a single nonblank bootstrap line: " + "Consumer guidance bridge must keep the export-guidance one-liner plus a short " + "discover-vs-isolate pointer (not the full guide): " + relative ) + first_line = nonblank_lines[0] if nonblank_lines else "" for required in ( "DiagnosticCli", "export-guidance", ".pickleball/AGENT-GUIDE.md", + ): + if required not in first_line: + errors.append( + f"Consumer guidance bridge one-liner must reference {required}: {relative}" + ) + + for required in ( + "mcp .", + "workbench_", + "mvn test", + "diagnostic", ): if required not in text: errors.append( - f"Consumer guidance bridge must reference {required}: {relative}" + f"Consumer guidance bridge must state the discover-vs-isolate split ({required}): " + + relative ) + lowered = text.lower() + if "do not skip workbench" not in lowered: + errors.append( + "Consumer guidance bridge must say not to skip Workbench when MCP is disconnected: " + + relative + ) + if "do not start the gui" not in lowered: + errors.append( + "Consumer guidance bridge must say not to start the GUI: " + relative + ) + for forbidden in ( "GUIDANCE-MANIFEST.json", ".git/info/exclude", "pkb_changed_variables", "runProfileFingerprint", "Diagnostic investigation protocol", + "attach.json", + "ui .", ): if forbidden in text: errors.append( f"Consumer guidance bridge contains dependency-owned guidance ({forbidden}); " - "keep only the bootstrap command and generated-guide pointer: " + "keep only the bootstrap command and a short discover-vs-isolate pointer: " + relative ) diff --git a/src/main/resources/META-INF/pickleball/guidance/AGENT-GUIDE.md b/src/main/resources/META-INF/pickleball/guidance/AGENT-GUIDE.md index 257ae6da..47f5ee81 100644 --- a/src/main/resources/META-INF/pickleball/guidance/AGENT-GUIDE.md +++ b/src/main/resources/META-INF/pickleball/guidance/AGENT-GUIDE.md @@ -6,12 +6,14 @@ A consumer project may contain only a short `AGENTS.md` bridge. That bridge can ## Tool chooser -Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`). Do not start the Workbench GUI. +Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`) to isolate a known failure. Do not start the Workbench GUI. -1. **Live headless MCP** — isolate a failing step in a paused worker. Reuse compilation, rewrite Gherkin in the live buffer, and inspect the page and semantic events in the same browser/Mapping state. -2. **One diagnostic `mvn test`** — after the live loop has isolated the failure, run one bounded confirmation with `pkb_runvars` so an evidence pack is retained. -3. **Emit the human handoff** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. -4. **Edit real consumer source** — change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. +1. **Discover** — when you do not yet know which scenarios fail, or you need many/parallel scenarios: run one diagnostic `mvn test` with `pkb_runvars` (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, the narrowest useful `pkb_tags`/`pkb_name`, and `pkb_parallel` when the project supports it). This is not a skip of Workbench; it is how you find failures. Do not start Workbench just to run the whole suite. +2. **Isolate / debug a known failing scenario** — use live headless Workbench MCP. If `workbench_*` MCP tools are not available in this session, start headless Workbench MCP first (`mcp .` via the documented Maven exec of `tools.dscode.launcher.PickleballWorkbenchLauncher`, `classpathScope=test`, args `mcp .`) and treat that as a required setup step — do not keep using `mvn test` for isolation/debug merely because MCP is disconnected. Prefer the IDE launching that command as an MCP stdio server (Copilot/Cursor MCP config) over a throwaway terminal you then ignore; stdio MCP only becomes tools if the IDE owns the process. After it is up: `workbench_sync` once, `workbench_worker_start`, `workbench_request_control`, then `workbench_execute_step` / `workbench_player_replace_document` / inspect. +3. **Confirm after isolation** — one bounded diagnostic `mvn test` with the existing AI defaults (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, narrowest useful `pkb_tags`/`pkb_name`). +4. **Emit the human handoff, then edit real consumer source** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. Change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. + +Missing `workbench_*` tools is a reason to start Workbench MCP, not a reason to skip it. A multi-scenario diagnostic test is a reason to run `mvn test` first, not a reason to skip Workbench afterward. Do not copy consumer features into `.pickleball` as a sandbox. @@ -19,8 +21,8 @@ Do not copy consumer features into `.pickleball` as a sandbox. From the consumer project, with Pickleball on the test classpath: -1. Start the launcher with `mcp .` (not a GUI command). -2. Call `workbench_sync` once. The synchronizer skips Maven/Gradle when Java/build/dependencies are unchanged, and refreshes test resources without a full `test-compile` when only features/config/data changed. +1. If `workbench_*` tools are not already in this session, start the launcher with `mcp .` (not a GUI command). Prefer the IDE owning that process as an MCP stdio server. +2. Call `workbench_sync` once. The agent must call it; Workbench does not auto-watch. Full compile when there is no live classpath or when Java/`pom`/dependencies changed; resources-only for feature/config/data; skip when unchanged. Live buffer edits need no sync. 3. `workbench_worker_start` — reuse the compiled live classpath; do not rebuild to start a worker. 4. `workbench_request_control` 5. Isolate with `workbench_execute_step` and/or `workbench_player_replace_document`. @@ -44,7 +46,7 @@ Worker restart without rebuild already exists (`workbench_worker_restart`). Step Keep first-read small. After a successful export: 1. Follow the consumer project's own instructions first; they remain authoritative for project-specific behavior. -2. Stay in this guide's tool chooser and live loop. +2. Stay in this guide's tool chooser: discover with a diagnostic `mvn test` when the failing scenario is unknown; isolate a known failure with the live headless MCP loop. 3. Inspect the **real** consumer `pom.xml`, Pickleball runner subclass, features, configuration, data, mappings, and test support before changing them. 4. Open a specific exported guide only when that topic is needed, for example `docs/dynamic-steps.md`, `docs/diagnostic-reporting.md`, `docs/configuration.md`, or `docs/ai-run-configuration.md`. 5. Do not assume the Pickleball core source repository is present. A normal consumer may only have the Maven dependency. diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md b/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md index efb17fb1..5b8dde8b 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/agent/README.md @@ -18,9 +18,9 @@ This directory supports repository-native AI coding agents. It is not a runtime Agent adapters should remain small and point back to the canonical contract rather than copying the full project description. -The nested `/maven-consumer-project/AGENTS.md` is intentionally only a dependency-owned guidance bootstrap. It materializes version-matched guidance and directs the consumer agent to `.pickleball/AGENT-GUIDE.md`. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. +The nested `/maven-consumer-project/AGENTS.md` is a dependency-owned guidance bootstrap plus a short discover-vs-isolate pointer. It materializes version-matched guidance, directs the consumer agent to `.pickleball/AGENT-GUIDE.md`, and states that a diagnostic `mvn test` finds which scenarios fail while headless Workbench MCP (`mcp .`) isolates a known failure. Refresh/version/manifest semantics, authoring rules, configuration, diagnostics, and troubleshooting belong in the exported dependency guidance. -The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same one-line bootstrap for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. +The nested `/maven-consumer-project/.github/copilot-instructions.md` is the same bootstrap-plus-pointer for IntelliJ Copilot Chat, which reads that file rather than `AGENTS.md`. The nested `/maven-consumer-project/README.md` is ordinary sample-project documentation. It may point humans and agents at `AGENTS.md` for guidance export, but should not duplicate the AI guidance lifecycle. diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md b/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md index 2537fd37..05efac3d 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/agent/feature-map.md @@ -47,6 +47,6 @@ The canonical worker bootstrap environment is `PKB_CONTROL_BRIDGE_SESSION_DIR`, `WorkbenchLiveSession` binds operations to the controller-owned paused scenario and verifies worker PID, bridge runtime id, and scenario id stability. A `FAILED` `executeStep` result leaves that same paused worker available; it is not a worker-ending error. Step Override source is compiled and loaded worker-side. Normal live calls do not invoke Maven/Gradle, resynchronize, or restart the worker. -The lightweight non-Spring stdio MCP adapter and player-style Swing/WebView UI both delegate through `WorkbenchServices` / `WorkbenchController`. `LiveScenarioPlayer` is a Workbench-side headless presentation model for the editable session buffer, stable line identities, selection, click-to-seek playhead, and player state only; it does not parse or execute Pickleball steps, model ParsingMap/NodeMap semantics, or claim runtime rewind. `LiveEditorView` is the Text vs Blocks presentation choice for that same buffer; toggling it must not change document text, selection, or playhead id. While `RUNNING`, `WorkbenchController.executeStep` owns playhead follow once (`LivePlaybackCoordinator.followExecutedStep`); the Swing Play loop continues without remaking that mark, and leftover marks of an already-consumed step are no-ops. The controller also owns the watched-agent control lease (`HUMAN` / `AGENT`, banner `currentAction`, gated Save permission). Consumer AI agents use headless MCP (`mcp .`). UI mode may write a localhost attach endpoint to `.pickleball/workbench/attach.json` so a watcher can join a human GUI session instead of starting a second Workbench; that attach file is not the consumer-agent path for this release. The left-rail picker filters project-owned scenarios by name (starts with / contains / ends with / full match; default contains; case-insensitive) and Cucumber tags (include AND, exclude NOT, Feature/Rule/outline/Examples inheritance parsed from catalog `.feature` files without calling Cucumber). Feature-file selection is an optional collapsed secondary filter; with none selected, name/tag apply to every catalog scenario. The live editor is Gherkin text or a block WebView over that same player model. Global Play starts from the first executable step; Step Editor **Step** is isolated `executeStep`; **From Here** runs from the selected step; wait-at-end stays in play so Enter can append-and-continue. Mapping property types go through `mappingPut` / `mappingRestore`. Terminal tails existing worker log files. Diagnostic explorer reads retained `reports/diagnostic-runs` artifacts in the repository evidence order. The default buffer is a Workbench-owned browser demo against `URL.home`; **Save** is confirmation-gated and copies only a picker-loaded scenario back to its originating `.feature` file. OpenJFX is Workbench-only. MCP mode reserves stdout for newline-delimited MCP JSON-RPC and redirects ordinary output to stderr. The UI remains execution-oriented and does not recreate a project IDE, generic build/process UI, source navigator, or collaboration system. +The lightweight non-Spring stdio MCP adapter and player-style Swing/WebView UI both delegate through `WorkbenchServices` / `WorkbenchController`. `LiveScenarioPlayer` is a Workbench-side headless presentation model for the editable session buffer, stable line identities, selection, click-to-seek playhead, and player state only; it does not parse or execute Pickleball steps, model ParsingMap/NodeMap semantics, or claim runtime rewind. `LiveEditorView` is the Text vs Blocks presentation choice for that same buffer; toggling it must not change document text, selection, or playhead id. While `RUNNING`, `WorkbenchController.executeStep` owns playhead follow once (`LivePlaybackCoordinator.followExecutedStep`); the Swing Play loop continues without remaking that mark, and leftover marks of an already-consumed step are no-ops. The controller also owns the watched-agent control lease (`HUMAN` / `AGENT`, banner `currentAction`, gated Save permission). Consumer AI agents discover unknown or multi-scenario failures with a diagnostic `mvn test`, then isolate a known failure with headless MCP (`mcp .`); missing `workbench_*` tools means start that stdio server, not skip Workbench. UI mode may write a localhost attach endpoint to `.pickleball/workbench/attach.json` so a watcher can join a human GUI session instead of starting a second Workbench; that attach file is not the consumer-agent path for this release. The left-rail picker filters project-owned scenarios by name (starts with / contains / ends with / full match; default contains; case-insensitive) and Cucumber tags (include AND, exclude NOT, Feature/Rule/outline/Examples inheritance parsed from catalog `.feature` files without calling Cucumber). Feature-file selection is an optional collapsed secondary filter; with none selected, name/tag apply to every catalog scenario. The live editor is Gherkin text or a block WebView over that same player model. Global Play starts from the first executable step; Step Editor **Step** is isolated `executeStep`; **From Here** runs from the selected step; wait-at-end stays in play so Enter can append-and-continue. Mapping property types go through `mappingPut` / `mappingRestore`. Terminal tails existing worker log files. Diagnostic explorer reads retained `reports/diagnostic-runs` artifacts in the repository evidence order. The default buffer is a Workbench-owned browser demo against `URL.home`; **Save** is confirmation-gated and copies only a picker-loaded scenario back to its originating `.feature` file. OpenJFX is Workbench-only. MCP mode reserves stdout for newline-delimited MCP JSON-RPC and redirects ordinary output to stderr. The UI remains execution-oriented and does not recreate a project IDE, generic build/process UI, source navigator, or collaboration system. For this boundary, scenario validation is limited to the affected `@control-bridge` and/or `@step-override-bridge` tags with `pkb_parallel=80` where practical. Do not run `@all` for Workbench isolation changes. diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-agent-guide.md b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-agent-guide.md index 257ae6da..47f5ee81 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-agent-guide.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-agent-guide.md @@ -6,12 +6,14 @@ A consumer project may contain only a short `AGENTS.md` bridge. That bridge can ## Tool chooser -Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`). Do not start the Workbench GUI. +Use this order. Consumer AI agents for this Pickleball release use headless Workbench MCP (`mcp .`) to isolate a known failure. Do not start the Workbench GUI. -1. **Live headless MCP** — isolate a failing step in a paused worker. Reuse compilation, rewrite Gherkin in the live buffer, and inspect the page and semantic events in the same browser/Mapping state. -2. **One diagnostic `mvn test`** — after the live loop has isolated the failure, run one bounded confirmation with `pkb_runvars` so an evidence pack is retained. -3. **Emit the human handoff** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. -4. **Edit real consumer source** — change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. +1. **Discover** — when you do not yet know which scenarios fail, or you need many/parallel scenarios: run one diagnostic `mvn test` with `pkb_runvars` (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, the narrowest useful `pkb_tags`/`pkb_name`, and `pkb_parallel` when the project supports it). This is not a skip of Workbench; it is how you find failures. Do not start Workbench just to run the whole suite. +2. **Isolate / debug a known failing scenario** — use live headless Workbench MCP. If `workbench_*` MCP tools are not available in this session, start headless Workbench MCP first (`mcp .` via the documented Maven exec of `tools.dscode.launcher.PickleballWorkbenchLauncher`, `classpathScope=test`, args `mcp .`) and treat that as a required setup step — do not keep using `mvn test` for isolation/debug merely because MCP is disconnected. Prefer the IDE launching that command as an MCP stdio server (Copilot/Cursor MCP config) over a throwaway terminal you then ignore; stdio MCP only becomes tools if the IDE owns the process. After it is up: `workbench_sync` once, `workbench_worker_start`, `workbench_request_control`, then `workbench_execute_step` / `workbench_player_replace_document` / inspect. +3. **Confirm after isolation** — one bounded diagnostic `mvn test` with the existing AI defaults (`pkb_reportingmode=diagnostic`, `pkb_loglevel=warn`, `pkb_reportretention=failed`, narrowest useful `pkb_tags`/`pkb_name`). +4. **Emit the human handoff, then edit real consumer source** — write `.pickleball/investigations//` then in chat print only `.pickleball/investigations//report.html`. Change the project's own features/Java only after the live buffer is right. Explicit Save is what writes a `.feature` file. + +Missing `workbench_*` tools is a reason to start Workbench MCP, not a reason to skip it. A multi-scenario diagnostic test is a reason to run `mvn test` first, not a reason to skip Workbench afterward. Do not copy consumer features into `.pickleball` as a sandbox. @@ -19,8 +21,8 @@ Do not copy consumer features into `.pickleball` as a sandbox. From the consumer project, with Pickleball on the test classpath: -1. Start the launcher with `mcp .` (not a GUI command). -2. Call `workbench_sync` once. The synchronizer skips Maven/Gradle when Java/build/dependencies are unchanged, and refreshes test resources without a full `test-compile` when only features/config/data changed. +1. If `workbench_*` tools are not already in this session, start the launcher with `mcp .` (not a GUI command). Prefer the IDE owning that process as an MCP stdio server. +2. Call `workbench_sync` once. The agent must call it; Workbench does not auto-watch. Full compile when there is no live classpath or when Java/`pom`/dependencies changed; resources-only for feature/config/data; skip when unchanged. Live buffer edits need no sync. 3. `workbench_worker_start` — reuse the compiled live classpath; do not rebuild to start a worker. 4. `workbench_request_control` 5. Isolate with `workbench_execute_step` and/or `workbench_player_replace_document`. @@ -44,7 +46,7 @@ Worker restart without rebuild already exists (`workbench_worker_restart`). Step Keep first-read small. After a successful export: 1. Follow the consumer project's own instructions first; they remain authoritative for project-specific behavior. -2. Stay in this guide's tool chooser and live loop. +2. Stay in this guide's tool chooser: discover with a diagnostic `mvn test` when the failing scenario is unknown; isolate a known failure with the live headless MCP loop. 3. Inspect the **real** consumer `pom.xml`, Pickleball runner subclass, features, configuration, data, mappings, and test support before changing them. 4. Open a specific exported guide only when that topic is needed, for example `docs/dynamic-steps.md`, `docs/diagnostic-reporting.md`, `docs/configuration.md`, or `docs/ai-run-configuration.md`. 5. Do not assume the Pickleball core source repository is present. A normal consumer may only have the Maven dependency. diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md index 35845161..996ae1a1 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/consumer-project.md @@ -26,7 +26,7 @@ Rerun export before Pickleball work even when `.pickleball` already exists. A su Compatibility note: an older Pickleball release whose exporter predates the manifest lifecycle may leave newer files or a newer manifest behind after a downgrade. Those leftovers are not authoritative for the downgraded dependency; prefer the dependency actually resolved on the test classpath and the files freshly exported by that dependency. -AI agents should read `.pickleball/AGENT-GUIDE.md` first after a successful export. That guide's tool chooser is the agent path: headless Workbench MCP (`mcp .`), one bounded diagnostic `mvn test`, then edits to the real consumer source. Do not treat `.pickleball/maven-consumer-project/` as the project under test, and do not dump `docs/README.md` or the whole snapshot into first-read context. Human readers can start with `.pickleball/docs/README.md`; links from those guides to `maven-consumer-project` resolve to the exported version-matched reference files. +AI agents should read `.pickleball/AGENT-GUIDE.md` first after a successful export. That guide's tool chooser is the agent path: one diagnostic `mvn test` to discover which scenarios fail when that is still unknown; live headless Workbench MCP (`mcp .`) to isolate a known failure (start the stdio server if `workbench_*` tools are missing; do not skip Workbench because MCP is disconnected); one bounded diagnostic confirmation; then edits to the real consumer source. Do not treat `.pickleball/maven-consumer-project/` as the project under test, and do not dump `docs/README.md` or the whole snapshot into first-read context. Human readers can start with `.pickleball/docs/README.md`; links from those guides to `maven-consumer-project` resolve to the exported version-matched reference files. ## Version-matched reference snapshot diff --git a/src/main/resources/META-INF/pickleball/guidance/docs/pickleball-workbench.md b/src/main/resources/META-INF/pickleball/guidance/docs/pickleball-workbench.md index 632d190c..26ae2d4e 100644 --- a/src/main/resources/META-INF/pickleball/guidance/docs/pickleball-workbench.md +++ b/src/main/resources/META-INF/pickleball/guidance/docs/pickleball-workbench.md @@ -58,7 +58,7 @@ mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java \ mvn -q org.codehaus.mojo:exec-maven-plugin:3.5.0:java "-Dexec.mainClass=tools.dscode.launcher.PickleballWorkbenchLauncher" "-Dexec.classpathScope=test" "-Dexec.args=mcp ." ``` -Humans who want the Swing player can pass `ui .` instead. With no launcher arguments, `ui` and the current directory are selected automatically for that human default. Other Workbench commands are forwarded in the same form, for example `"-Dexec.args=sync ."`. Agents for this release should not use the GUI, `ui .`, or `.pickleball/workbench/attach.json` as their path; see `.pickleball/AGENT-GUIDE.md`. +Humans who want the Swing player can pass `ui .` instead. With no launcher arguments, `ui` and the current directory are selected automatically for that human default. Other Workbench commands are forwarded in the same form, for example `"-Dexec.args=sync ."`. Consumer agents start `mcp .` when isolating a known failure. They may run a diagnostic `mvn test` first to discover which of several scenarios fail. Missing `workbench_*` tools means start this stdio server, not skip Workbench. Agents for this release should not use the GUI, `ui .`, or `.pickleball/workbench/attach.json` as their path; see `.pickleball/AGENT-GUIDE.md`. Gradle consumers can expose the same dependency-owned launcher without resolving a cache path or adding a Workbench dependency: @@ -321,7 +321,7 @@ Start the lightweight non-Spring MCP server for a consumer project. This is the java -jar $workbenchJar mcp ".\maven-consumer-project" ``` -Or, from a Maven consumer test classpath, `"-Dexec.args=mcp ."`. Do not document or use the Swing GUI as the agent path. +Or, from a Maven consumer test classpath, `"-Dexec.args=mcp ."`. Consumer agents start this stdio server when isolating a known failure. They may first run a diagnostic `mvn test` to discover which scenarios fail. Missing `workbench_*` tools means start this server (preferably as an IDE-owned MCP process), not skip Workbench. Do not document or use the Swing GUI, `ui .`, or `.pickleball/workbench/attach.json` as the agent path. The server uses the official Java MCP SDK core and stdio transport with the Jackson 2 JSON adapter. MCP dependencies are Workbench-only and are shaded into the executable companion. Workbench deliberately does not use Spring Boot, Spring Framework, Spring AI, WebMVC, or Tomcat.