EBP-2889: Address session-analysis feedback on solace-application-development

plugins/solace-messaging-skills/skills/solace-application-development/SKILL.md

@@ -20,7 +20,7 @@ This skill is the front door for building Solace messaging applications grounded
 
 ## What is Solace
 
-Ground the developer in the high-level model before discussing patterns or generating code. Solace is an event-driven messaging platform: an event broker carries messages between applications, brokers connect into an event mesh, publishers send to named topics, and consumers read either directly or from durable queues that subscribe to those topics (the publish and subscribe model). Solace Cloud is the primary broker this skill assumes for the work it generates; a self-hosted Software Broker or an existing Appliance are supported alternatives. Point the developer at the canonical [Solace Core Concepts](https://docs.solace.com/Get-Started/event-mesh-basics.md) page for the grounding, confirm they grasp the publish/subscribe and queue concepts, then continue. Do not paraphrase the page; link it.
+Solace is an event-driven messaging platform: an event broker carries messages between applications, brokers connect into an event mesh, publishers send to named topics, and consumers read either directly or from durable queues that subscribe to those topics (the publish and subscribe model). Solace Cloud is the primary broker this skill assumes for the work it generates; a self-hosted Software Broker or an existing Appliance are supported alternatives. The canonical [Solace Core Concepts](https://docs.solace.com/Get-Started/event-mesh-basics.md) page is the doc grounding for this model.
 
 For topic-hierarchy and topic-architecture design questions, the co-installed solace-topic-best-practices skill reads the canonical Topic Architecture Best Practices page online and applies it to those decisions.
 
@@ -39,8 +39,11 @@ If the API is unclear but the request is clearly about Solace messaging in Java,
 Non-negotiable rules that apply across every API. Apply all.
 
 1. **Content sourcing**: Every named entity (API, parameter, configuration value) must be traceable to a canonical Solace source. Do not assert behavior, defaults, or best practices that are not in the grounding documentation.
-2. **WebFetch-on-demand doc grounding**: This skill bundles no documentation. When a step needs documentation content to ground a generation or design decision, WebFetch the live canonical page on demand (its `docs.solace.com` `.md` URL, the same link the reference files carry), then quote or summarize the fetched page. Do not answer from memory and do not paraphrase guidance the page does not contain. Do not restate doc content in the skill; link the live `.md` URL. A short list of references stays live for the same reason it always has (Javadoc HTML, the Java API Release Notes, Maven Central, the tutorials, and the GitHub samples) because those have no `docs.solace.com` `.md` form.
-3. **No hardcoded versions**: Never pin a library version anywhere in skill content. The generated build resolves the latest release of the relevant Solace coordinate at generation time. Each API's entry file names the exact coordinate to use.
+2. **WebFetch-on-demand doc grounding**: This skill bundles no documentation. When a step needs documentation content to ground a generation or design decision, WebFetch the live canonical page on demand (its `docs.solace.com` `.md` URL, the same link the reference files carry), then quote or summarize the fetched page. Do not answer from memory and do not paraphrase guidance the page does not contain. Do not restate doc content in the skill; link the live `.md` URL. Never substitute another channel for that WebFetch: grounding taken from a docs chatbot, a search tool, or decompiling a jar does not satisfy this invariant, and a page never fetched in the session must never be cited as grounding. A short list of references stays live for the same reason it always has (Javadoc HTML, the JCSMP API Release Notes, Maven Central, the tutorials, and the GitHub samples) because those have no `docs.solace.com` `.md` form.
+3. **No hardcoded versions**: Never pin a library version anywhere in skill content. The generated build resolves the latest release of every dependency at generation time from the AUTHORITATIVE Maven repository metadata; each API's entry file names the exact coordinate and carries the exact lookup command. Never read a version from the legacy `search.maven.org/solrsearch` index: it lags the repository metadata and reports stale versions. Security floors (a minimum version below which known CVEs live) are enforced as checks on the resolved result, never as pins.
+4. **AI-assisted disclaimer header**: Every source file generated under this skill starts with this exact line: `AI-assisted code. Review before production use.` Directly below it: `See the verification checklist: solace-verification-checklist.md`. This applies to EVERY generated source file, including custom builds, web apps, and embedded shapes that adapt the reference samples outside the canonical generator. The pom and other non-source artifacts are exempt; the bundled reference samples themselves carry no header.
+5. **Verification artifacts, always**: Any session that generates Solace code from this skill writes a tailored `solace-verification-checklist.md` beside the code as generation output, copies the bundled `verify.sh` (plus its generated `verify-hooks.sh`) into the project, and ends in a real verify run or the compile-only fallback with the exact handed-back commands. The `VERIFY:` markers are non-optional in generated Solace messaging code, whatever the app shape. An improvised check (for example curl against the app's own HTTP API) may TRIGGER traffic but never renders the verdict; the verdict comes from the markers and the verify exit code.
+6. **Live-broker heads-up**: Immediately before starting ANY process that will connect to a live broker — verify.sh, `java -jar`, a `mvn` run, a run script, anything — print one line that names the broker host and states the actual broker-side effects of this run (the queues it provisions, the connections it opens, the messages it publishes), scaled to the real app. Environment discovery is never consent and never an answer: a running local broker, an existing config file, or found credentials are facts to report, not answers to consume; report them, then still ask which broker the developer wants to target.
 
 ## Reference Files (read on-demand only)
 

plugins/solace-messaging-skills/skills/solace-application-development/references/jcsmp.md

@@ -6,19 +6,37 @@ The cross-cutting invariants (content sourcing, WebFetch-on-demand doc grounding
 
 ## Mode Detection
 
-Determine the user's intent and enter the appropriate mode:
+Determine the user's intent and enter the appropriate mode. Routing is keyed on the design contract, not on the phrasing of the request: Implement mode never starts without a confirmed design (the design-contract gate below), so a "build me..." prompt is NOT an Implement signal by itself.
 
 | User intent | Mode | What to do |
 |---|---|---|
 | "Help me choose the Solace JCSMP messaging pattern for a new app" / "Topic or queue?" / "What delivery semantics should I use?" | **Design** | Read `jcsmp/design-mode.md` |
-| "Build me a Solace JCSMP publisher/consumer app" / "Generate a Maven JCSMP project" / "Publish to a topic and consume from a queue" | **Implement** | Read `jcsmp/implement-mode.md` |
+| Build or generate a NEW app or messaging component with NO valid design contract yet — "Build me a Solace JCSMP publisher/consumer app", "Generate a Maven JCSMP project", a web app / dashboard / service, Spring Boot, or any embedded shape where the JCSMP layer lives inside a larger application | **Design first** | Read `jcsmp/design-mode.md`. A prompt that already states the design resolves on its fully-specified path in ONE confirm; a bare prompt walks the tree. The confirmed summary then feeds Implement. |
+| A build request WITH a valid design contract (see the design-contract gate below) | **Implement** | Read `jcsmp/implement-mode.md`; for an embedded shape generate the messaging layer per its leaf rules and verify with the `app` stage of `verify.sh` (its Step 5) |
+| An edit to an EXISTING app that changes the messaging topology (the topology rule below) | **Design first** | Re-enter `jcsmp/design-mode.md` to re-confirm the affected summary fields, then Implement applies the change |
+| A mechanical edit to an EXISTING app with no topology change — reconnect handling, payload format, logging, renames, ack tuning | **Implement** | Read `jcsmp/implement-mode.md`; no design pass |
 | "My JCSMP app is throwing on connect" / "Why is my consumer not binding the queue?" | **Debug** | Debug mode is not yet available in this release. Redirect the user to the canonical Solace JCSMP troubleshooting documentation: [JCSMP API Home](https://docs.solace.com/API/Messaging-APIs/JCSMP-API/jcsmp-api-home.md). Do not generate debugging guidance from memory. |
 
 If unclear, default to **Design**. Understand the messaging problem before generating code.
 
+**The topology rule** decides between the two existing-app rows. An edit changes the messaging topology when it changes the structure the design summary records: a new app or messaging component (a new publisher, consumer, requestor, or replier, including a leaf change such as single-service growing into fan-out), a pattern change, a delivery-mode change, a consumption-endpoint change, or a queue access-type change. That list is the core; also treat an unlisted change as topology when your judgment says it alters the message flow between the apps and the broker. Everything else is a mechanical edit.
+
+Three gates hold on every path:
+
+- **The design-contract gate.** Implement mode never starts without a design contract, and never invents design values. Exactly three sources satisfy it: (1) a summary Design mode confirmed in this session — use it as-is, with no re-confirm; (2) an explicit summary the developer supplied in chat (the eight fields or an equivalent statement of them) — use it directly; (3) a saved `solace-design.md` in the project — restate it in one line and proceed on confirm. A prose build request that merely mentions pattern details is NOT a contract: route it through Design mode, whose fully-specified path derives the summary, echoes it, and takes one confirm. The one carve-out is the mechanical-edit row above. An experienced developer therefore never has to walk the design tree, but never skips the contract either.
+- **Implement mode opens with a mandatory door question.** Ask Quickstart, Solace Suggested, or Custom — before you request or accept ANY broker details (`jcsmp/implement-mode.md` Step 0). Ask it even when a `config.json` with credentials already exists, even when a local broker is already running, and even when the requested app is bigger than the canonical generated shape; none of those answers the question. A confirmed design summary does not answer it either: the door question always follows the design contract, never merges into it.
+- **Environment discovery never answers a question.** A running broker container, an existing config file, or found credentials are facts to report, not answers to consume. Report what you found, then still ask which broker the developer wants to target.
+
 ## JCSMP coordinate
 
-The single Solace dependency for this API is `com.solacesystems:sol-jcsmp`. Use the groupId `com.solacesystems` exactly; the shorter `com.solace` form does not resolve on Maven Central. Resolve the latest release at generation time (the no-hardcoded-versions invariant); never pin a `sol-jcsmp` version in skill content.
+The single Solace dependency for this API is `com.solacesystems:sol-jcsmp`. Use the groupId `com.solacesystems` exactly; the shorter `com.solace` form does not resolve on Maven Central. Resolve the latest release at generation time (the no-hardcoded-versions invariant); never pin a `sol-jcsmp` version in skill content. Resolve it from the authoritative metadata with exactly this command, and read the `<release>` element:
+
+```bash
+curl -s https://repo1.maven.org/maven2/com/solacesystems/sol-jcsmp/maven-metadata.xml \
+  | grep -oE '<release>[^<]+</release>'
+```
+
+Do NOT read the version from the legacy solrsearch index (`search.maven.org/solrsearch`): it lags behind the repository metadata and reports a stale `latestVersion`.
 
 ## Canonical doc links
 
@@ -31,17 +49,20 @@ JCSMP-specific grounding. Each page below is a live `docs.solace.com` `.md` URL,
 Live exceptions (these have no `docs.solace.com` `.md` form; use the live URL directly):
 
 - [JCSMP Javadoc](https://docs.solace.com/API-Developer-Online-Ref-Documentation/java/index.html)
-- [Java API Release Notes](https://products.solace.com/download/JAVA_API_RN)
+- [JCSMP API Release Notes](https://products.solace.com/download/JAVA_API_RN) (the `JAVA_API_RN` download serves the JCSMP release notes; it is NOT the newer Solace Messaging API for Java)
 - [sol-jcsmp on Maven Central](https://central.sonatype.com/artifact/com.solacesystems/sol-jcsmp)
 
 ## Mode and reference files (read on-demand only)
 
-- `jcsmp/prerequisites.md`: Solace core-concepts grounding and broker acquisition (route here first if the developer has no reachable broker).
-- `jcsmp/design-mode.md`: choose the messaging pattern/topology before generating code.
-- `jcsmp/implement-mode.md`: generate a runnable Maven JCSMP pub/sub project.
+- `jcsmp/prerequisites.md`: broker acquisition (route here first if the developer has no reachable broker).
+- `jcsmp/design-mode.md`: choose and confirm the messaging pattern/topology before any code is generated; every new build without a design contract routes here first.
+- `jcsmp/implement-mode.md`: generate a runnable Maven JCSMP project from a confirmed design (any leaf, any app shape); its Step 4 dispatches onto the per-leaf wiring files below.
+- `jcsmp/implement-guaranteed-pubsub.md`: the Guaranteed Pub/Sub leaf wiring (read from implement-mode Step 4).
+- `jcsmp/implement-direct-pubsub.md`: the Direct Pub/Sub leaf wiring (read from implement-mode Step 4).
+- `jcsmp/implement-request-reply.md`: both Request-Reply leaf wirings (read from implement-mode Step 4).
 - `jcsmp/solace-suggested-mode.md`: the leaf-agnostic Solace Suggested overlay (TLS secure session, DMQ on PERSISTENT, HA failover, separate Maven projects) reached from implement-mode Step 0 on the Solace Suggested path.
 - `jcsmp/custom-mode.md`: the thin a la carte Custom overlay reached from implement-mode Step 0 on the Custom path; a leaf-aware checklist of the hardening knobs (secure session, DMQ, HA, decoupled projects, admin-provisioned queue) that generates exactly the ticked subset, reusing the Solace Suggested overlay steps for the mapped knobs.
-- `jcsmp/verification-checklist.md`: the master template of binary verification checks organized into three responsibility groups (delivered by this generation, the developer's responsibility, and verified by the round-trip); Implement mode Step 6 emits a tailored `solace-verification-checklist.md` into each generated project seeded for the chosen mode and reports the same in chat.
-- `jcsmp/scripts/verify.sh`: the bundled stage-dispatched run-and-observe verify script (`verify.sh <publisher|consumer|roundtrip|direct|direct-request-reply|guaranteed-request-reply> <host:port> <vpn> <user> [pass]`) that Implement mode runs per generation stage against a reachable broker.
+- `jcsmp/verification-checklist.md`: the master template of binary verification checks organized into responsibility groups (delivered by this generation, the developer's responsibility, verified by the round-trip, and generation conformance); Implement mode Step 4 writes a tailored `solace-verification-checklist.md` into each generated project as generation output, and Step 6 reports the same resolution in chat.
+- `jcsmp/scripts/verify.sh`: the bundled stage-dispatched run-and-observe verify script (`verify.sh <publisher|consumer|roundtrip|direct|direct-request-reply|guaranteed-request-reply|app> ...`) that Implement mode copies into every generated project and runs against a reachable broker; the `app` stage drives web and embedded shapes through a generated `verify-hooks.sh`.
 - `jcsmp/jcsmp-guaranteed-publisher-sample.java`: best-practices publisher sample (basic-auth connect, PERSISTENT publish to a topic, graceful shutdown).
 - `jcsmp/jcsmp-guaranteed-subscriber-sample.java`: best-practices consumer sample (provisions a durable queue + topic subscription, CLIENT-ack flow).

plugins/solace-messaging-skills/skills/solace-application-development/references/jcsmp/custom-mode.md

@@ -2,7 +2,7 @@
 
 The Custom overlay for Implement mode. This file is reached from `implement-mode.md` Step 0 when the developer chooses the Custom door. Custom is a la carte: the developer ticks which hardening knobs to include, and generation applies exactly the ticked subset and nothing more. It is a thin overlay. It does NOT re-describe how each knob works. For the four knobs that map to a `solace-suggested-mode.md` step, it points at that step and reuses it, so `solace-suggested-mode.md` stays the single source of truth for each hardening delta.
 
-This overlay defers to `implement-mode.md` for all leaf and sample mechanics, exactly the way `solace-suggested-mode.md` does: the Step 2 design-summary input contract, the Step 4 leaf dispatch (which sample pair each leaf reads, and the near-verbatim adaptation discipline), the AI-assisted disclaimer header on every generated class, the explicit single-class imports invariant (keep every import explicit, per `implement-mode.md`; never collapse to a wildcard), and the four-file `VERIFY:` marker contract. Custom adds NO verify stage and changes NO `VERIFY:` marker string.
+This overlay defers to `implement-mode.md` for all leaf and sample mechanics, exactly the way `solace-suggested-mode.md` does: the Step 2 design-summary input contract, the Step 4 leaf dispatch (which leaf wiring file and sample pair each leaf reads, and the near-verbatim adaptation discipline), the AI-assisted disclaimer header on every generated class, the explicit single-class imports invariant (keep every import explicit, per `implement-mode.md`; never collapse to a wildcard), and the fixed `VERIFY:` marker contract. Custom adds NO verify stage and changes NO `VERIFY:` marker string. Any live run on the Custom path prints the same one-line live-broker heads-up (SKILL.md Invariant 6) immediately before it starts: name the broker host and the run's actual broker-side effects.
 
 ## The checklist model: one up-front multi-select
 
@@ -62,7 +62,7 @@ Because the ticked app no longer provisions anything, an autonomous round-trip w
 
 ## Return to the implement-mode contracts
 
-After capturing the ticked subset and applying the deltas above, return to `implement-mode.md` for the unchanged leaf mechanics: the Step 4 dispatch generates the chosen leaf's classes, and Step 6 resolves each `verification-checklist.md` item to its state for the Custom ticked subset, writes the tailored `solace-verification-checklist.md` into the project (one copy per project root when the decoupled-projects knob is ticked, otherwise one at the project root), invites the developer's additions, and reports the same in chat, the same way it does on Quickstart and Solace Suggested. This overlay selects which hardening deltas to layer; it does not replace those contracts.
+After capturing the ticked subset and applying the deltas above, return to `implement-mode.md` for the unchanged leaf mechanics: the Step 4 dispatch generates the chosen leaf's classes and writes the tailored `solace-verification-checklist.md` into the project as generation output (one copy per project root when the decoupled-projects knob is ticked, otherwise one at the project root), and Step 6 resolves each item to its state for the Custom ticked subset, invites the developer's additions, and reports the same in chat, the same way it does on Quickstart and Solace Suggested. This overlay selects which hardening deltas to layer; it does not replace those contracts.
 
 ## Grounding references