Close the 2.0.0 MiniSpec notes

Lessons promoted to core: Velocity and bash arrays, declared vs resolved
dependency versions, published POM shaping, JDK-dependent options from
the packaging JDK, isolated Maven repo in smoke tests, Gradle Plugin
Portal and release candidates. The 2.0.0 fix, CI and release notes are
deleted; the pending dependency follow-ups move to the new
dependabot-alerts note (#500).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: fvarrui

.minispec/core/conventions.md

@@ -9,6 +9,11 @@
 - Platform-specific options go in `WindowsConfig`, `MacConfig` or `LinuxConfig`, not in `PackagerSettings`.
 - New artifacts are `ArtifactGenerator` subclasses. Platform and external-tool checks go in `skip()`, not in `doApply()`.
 - Template names and the variables they use are public API: users override them from `assetsDir`. Renaming a template or changing its variables is a breaking change.
+- In `.vtl` templates, Velocity reads bash `${name[@]}` as its own reference and fails: wrap such lines in `#[[ ... ]]#` (they must not contain Velocity references). `${#name[@]}` is fine.
+- Dependency versions: Maven consumers get the version declared in `build.gradle` (nearest wins), Gradle the highest in the graph. Declare the version Gradle resolves, so both use the same jar (`check-deps` skill).
+- The published POM is edited in `pom.withXml`: Maven APIs (`maven-plugin-api`, `maven-core`) are `provided`, Maven plugins used as libraries (`mojo-executor`, `jdeb`) exclude `org.apache.maven:*`, and Gradle-only dependencies (the launch4j Gradle library) and repositories stay out. Gradle consumers use the `.module` file instead.
+- JDK-dependent options (`jlink`, `jdeps`) follow the packaging JDK's version (`JDKUtils.getJavaMajorVersion(File)`), not the Java running Maven or Gradle (`jdeps` still uses the running one). JDK 24+ may come without `jmods` (JEP 493).
+- Smoke tests resolve from an empty local Maven repo (`-Dmaven.repo.local=build/m2-smoke`), like a user would: the embedded Maven fills `~/.m2` with artifacts users don't have.
 - Log through `utils/Logger`, never `System.out`.
 - Run external tools through `utils/CommandUtils`.
 - Bundled native binaries in `src/main/resources` are not edited by hand. `updateWhyJavaLauncher` refreshes `JavaLauncher.exe`; `updateNativeJavaApplicationStub` refreshes the native macOS launchers, whose source is in `javapackager/nativeJavaApplicationStub` (ADR-004).

.minispec/core/stack.md

@@ -10,7 +10,7 @@
 
 - Maven Plugin API, `mojo-executor`.
 - Gradle API, Launch4j Gradle plugin (`edu.sc.seis.launch4j`).
-- Apache Velocity 2.3 (templates).
+- Apache Velocity 2.4 (templates).
 - Commons IO, Lang3, Collections4, Compress.
 - `jdeb` (DEB), `redline` (RPM), `jsign-core` (Windows signing).
 
@@ -23,4 +23,6 @@
 
 ## Publishing
 
-- Maven Central through the Central Portal: snapshots repo, and releases (signed) through the Portal OSSRH Staging API (`releaseToCentral`).
+- Maven Central through the Central Portal: snapshots repo, and releases (signed) through the Portal OSSRH Staging API (`releaseToCentral`), then published by hand in the Portal. Release candidates (`X.Y.Z-rcN`) are published the same way.
+- Not published on the Gradle Plugin Portal: its repository (`plugins.gradle.org/m2`) redirects to Maven Central, so `plugins { id 'io.github.javapackager' version '...' }` works with no extra repositories (#490).
+- Dependabot sees the Gradle build through `.github/workflows/dependency-submission.yml`; version update PRs come from `.github/dependabot.yml`.

.minispec/features/ci-velocity-template-check.md

@@ -6,7 +6,7 @@ Catch Velocity parse errors in `src/main/resources/**/*.vtl` in a fast CI check,
 
 ## Context
 
-- A Velocity lexical error in `linux/startup.sh.vtl` (bash `"${name[@]}"` read as a Velocity reference) broke every GNU/Linux build in `devel`. It was only found when the Linux smoke test packaged the sample (see `fix-linux-startup-velocity-arrays.md`).
+- A Velocity lexical error in `linux/startup.sh.vtl` (bash `"${name[@]}"` read as a Velocity reference) broke every GNU/Linux build in `devel`. It was only found when the Linux smoke test packaged the sample (fixed with `#[[ ]]#`, see conventions).
 - Templates are rendered at packaging time by `utils/VelocityUtils`; nothing parses them during the build.
 - Users can override templates from `assetsDir`, so templates are public API and must stay valid.
 

.minispec/features/dependabot-alerts.md

@@ -0,0 +1,25 @@
+# Dependabot security alerts (#500)
+
+## Goal
+
+Clear the Dependabot alerts on `master`: fix the ones that reach users, and fix or dismiss with a reason the ones only in the plugin's own build.
+
+## Context
+
+- 23 open alerts after 2.0.0 (4 critical, 3 high, 15 moderate, 1 low), all from the Gradle dependency graph (`dependency-submission` workflow submits every configuration, `settings.gradle` as manifest).
+- Packages: Bouncy Castle (`bcprov`/`bcpkix` `jdk18on`, `bcprov`/`bcpg` `jdk15on`, 18 alerts), `maven-core` < 3.8.1, `maven-shared-utils` < 3.3.3, `aircompressor` < 2.0.3, `guava` < 32, `log4j-api` < 2.25.5.
+- Users get only what the published POM (Maven) or `.module` (Gradle) declares; the `mavenEmbedder` configuration (plugin descriptor generation) and the signing plugin never reach them.
+- Constraints: Java 8 bytecode, minimum Maven version set by `maven-plugin-api` 3.6.0, published POM shaping in `pom.withXml` (conventions).
+- Follow-ups left from the 2.0.0 dependency updates: `jsign-core` 6 → 7 (check Java 8 and API), `com.gradle.plugin-publish` 2.x, Gradle wrapper 9 (needs Java 17 to run Gradle), `redline` 1.2.10 (unmaintained, look for a replacement).
+
+## Changes
+
+- For each alerted package, find the dependency path (`./gradlew dependencyInsight --configuration <conf> --dependency <name>`) and whether it's published.
+- Published ones: update the direct dependency, or add a constraint, and check Java 8 bytecode (`check-deps` skill).
+- Build-only ones: update when cheap (e.g. the embedded Maven), otherwise dismiss with the reason.
+- Prefer `*-jdk18on` over the discontinued `*-jdk15on` Bouncy Castle artifacts.
+
+## Acceptance
+
+- No open alert for a dependency users download, or each remaining one dismissed with a reason in #500.
+- The smoke tests pass on every platform, and the published POM keeps no wrong-scope or Gradle-only dependency.