fix: address repository review findings

martinfrancois · martinfrancois · commit f0b01a8cf607 · 2026-06-06T12:04:21.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -50,18 +50,19 @@ jobs:
           print('JSON ok')
           PY
 
-      - name: Parse YAML files
+      - name: Validate YAML metadata
         run: |
           python3 - <<'PY'
           import pathlib
-          try:
-              import yaml
-          except ImportError:
-              print('PyYAML unavailable; skipping YAML parse')
-              raise SystemExit(0)
-          for path in list(pathlib.Path('.').rglob('*.yml')) + list(pathlib.Path('.').rglob('*.yaml')):
-              yaml.safe_load(open(path, encoding='utf-8'))
-          print('YAML ok')
+          from scripts.validate_skill import parse_openai_agent_metadata
+
+          for path in pathlib.Path('skills').glob('*/agents/openai.yaml'):
+              _, failures = parse_openai_agent_metadata(path.read_text(encoding='utf-8'))
+              if failures:
+                  for failure in failures:
+                      print(f'{path}: {failure}')
+                  raise SystemExit(1)
+          print('YAML metadata ok')
           PY
 
       - name: Lint Tessl plugin
diff --git a/.github/workflows/publish-tessl.yml b/.github/workflows/publish-tessl.yml
@@ -14,7 +14,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: publish-tessl-${{ github.event.release.tag_name || github.run_id }}
+  group: publish-tessl-${{ github.event.release.tag_name || inputs.ref || github.ref }}
   cancel-in-progress: false
 
 jobs:
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -28,21 +28,6 @@ jobs:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
-      - name: Trigger Tessl publish
-        if: ${{ steps.release.outputs.release_created == 'true' }}
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG_NAME: ${{ steps.release.outputs.tag_name }}
-        run: |
-          set -euo pipefail
-
-          if [ -z "${TAG_NAME:-}" ]; then
-            echo "Release Please reported a release but did not output tag_name." >&2
-            exit 1
-          fi
-
-          gh workflow run publish-tessl.yml --repo "$GITHUB_REPOSITORY" --ref main -f ref="$TAG_NAME"
-
       - name: Find release PR
         id: release-pr
         env:
diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
 # Java Streams Skill for AI Agents
 
-[![tessl](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.tessl.io%2Fv1%2Fbadges%2Fmartinfrancois%2Fjava-streams)](https://tessl.io/registry/martinfrancois/java-streams)
-
 AI agents often know Java streams well enough to chain `filter`, `map`, and `collect`, but not
 enough to choose the right stream operation for the job in new code, reviews, and cleanup.
 
@@ -33,7 +31,8 @@ may be different from the right code for Java 17, Java 21, or Java 24.
 
 ### 1. Install
 
-Install the published Tessl plugin using the option that fits your setup:
+This repository is private and the Tessl plugin has not been published yet. After the first public
+Tessl publish, install it using the option that fits your setup:
 
 | Tool | Command |
 | --- | --- |
diff --git a/docs/agents/readme.md b/docs/agents/readme.md
@@ -16,6 +16,8 @@ wording.
 - The README may say agents that support skill auto-selection, such as Codex and Claude Code, can
   select the skill from context.
 - Install examples should use `martinfrancois/java-streams`.
+- If the Tessl package is not published yet, say that clearly before install commands and do not add
+  live registry badges or links that currently 404.
 - Keep a table of contents after the intro and before `Getting Started`.
 - Avoid fixed benchmark claims unless they match the latest hosted eval run.
 - When discussing evals, distinguish main eval lift scenarios from reference/regression scenarios.
diff --git a/evals-reference/06-inventory-summary/criteria.json b/evals-reference/06-inventory-summary/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval stream cleanup: materialized intermediate lists and manual joining should become direct stream terminals while preserving Java 8 compatibility.",
+  "context": "Reference stream cleanup: materialized intermediate lists and manual joining should become direct stream terminals while preserving Java 8 compatibility.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/07-catalog-feed/criteria.json b/evals-reference/07-catalog-feed/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval cleanup: stream of Optionals, null-sensitive sorting, and duplicate-key collector behavior.",
+  "context": "Reference cleanup: stream of Optionals, null-sensitive sorting, and duplicate-key collector behavior.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/08-primary-contact-review/criteria.json b/evals-reference/08-primary-contact-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: reject a proposed findAny and parallelStream change that loses priority ordering.",
+  "context": "Reference review: reject a proposed findAny and parallelStream change that loses priority ordering.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/09-order-collector-report/criteria.json b/evals-reference/09-order-collector-report/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval implementation: choose stream collectors that express map and aggregate semantics without manual mutable loops.",
+  "context": "Reference implementation: choose stream collectors that express map and aggregate semantics without manual mutable loops.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/10-packet-window-cleanup/criteria.json b/evals-reference/10-packet-window-cleanup/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval cleanup: takeWhile/dropWhile are prefix operations; filter would silently change packet-window behavior.",
+  "context": "Reference cleanup: takeWhile/dropWhile are prefix operations; filter would silently change packet-window behavior.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/11-null-category-price-index/criteria.json b/evals-reference/11-null-category-price-index/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval implementation: collectors must preserve null-skip and duplicate-key behavior; naive toMap/groupingBy can throw or change semantics.",
+  "context": "Reference implementation: collectors must preserve null-skip and duplicate-key behavior; naive toMap/groupingBy can throw or change semantics.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/12-remote-stock-review/criteria.json b/evals-reference/12-remote-stock-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: parallelStream is a weak answer for blocking remote calls; Java 24 allows discussing Gatherers.mapConcurrent.",
+  "context": "Reference review: parallelStream is a weak answer for blocking remote calls; Java 24 allows discussing Gatherers.mapConcurrent.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/13-training-and-packets/criteria.json b/evals-reference/13-training-and-packets/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval implementation: Java 17 mapMulti is a strong fit for conditional developer email extraction, and takeWhile is required for prefix semantics.",
+  "context": "Reference implementation: Java 17 mapMulti is a strong fit for conditional developer email extraction, and takeWhile is required for prefix semantics.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/14-parallel-mutation-review/criteria.json b/evals-reference/14-parallel-mutation-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: parallel streams with shared mutable HashMap state are unsafe; collectors should own accumulation.",
+  "context": "Reference review: parallel streams with shared mutable HashMap state are unsafe; collectors should own accumulation.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/16-java11-report-review/criteria.json b/evals-reference/16-java11-report-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: Stream.toList is Java 16+ and returns an unmodifiable list, so this Java 11 change is both incompatible and behavior-breaking.",
+  "context": "Reference review: Stream.toList is Java 16+ and returns an unmodifiable list, so this Java 11 change is both incompatible and behavior-breaking.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/17-java8-optional-prefix-review/criteria.json b/evals-reference/17-java8-optional-prefix-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: Java 8 cannot use Optional.stream, takeWhile, or Stream.toList; the prefix behavior must still be preserved.",
+  "context": "Reference review: Java 8 cannot use Optional.stream, takeWhile, or Stream.toList; the prefix behavior must still be preserved.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/18-priority-findany-review/criteria.json b/evals-reference/18-priority-findany-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: findAny and parallelStream can break first-configured-value semantics on ordered inputs.",
+  "context": "Reference review: findAny and parallelStream can break first-configured-value semantics on ordered inputs.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/19-null-collector-review/criteria.json b/evals-reference/19-null-collector-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: toMap needs explicit null and duplicate-key handling to preserve loop behavior.",
+  "context": "Reference review: toMap needs explicit null and duplicate-key handling to preserve loop behavior.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/20-parallel-shared-state-review/criteria.json b/evals-reference/20-parallel-shared-state-review/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval review: parallelStream with forEach mutating a shared HashMap is unsafe; collector-owned accumulation is the correct stream shape.",
+  "context": "Reference review: parallelStream with forEach mutating a shared HashMap is unsafe; collector-owned accumulation is the correct stream shape.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/22-java8-version-scan/criteria.json b/evals-reference/22-java8-version-scan/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval audit: measures whether the agent uses the bundled hard-stop scan command to catch Java-version drift on a Java 8 baseline.",
+  "context": "Reference audit: measures whether the agent uses the bundled hard-stop scan command to catch Java-version drift on a Java 8 baseline.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/23-collector-order-scan/criteria.json b/evals-reference/23-collector-order-scan/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval audit: measures whether the agent uses the bundled hard-stop scan command to classify collector, ordering, null-sort, and parallel markers.",
+  "context": "Reference audit: measures whether the agent uses the bundled hard-stop scan command to classify collector, ordering, null-sort, and parallel markers.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/evals-reference/24-mutable-batch-modernization/criteria.json b/evals-reference/24-mutable-batch-modernization/criteria.json
@@ -1,5 +1,5 @@
 {
-  "context": "Main eval natural cleanup: Java 17 modernization often tempts agents to replace Collectors.toList with Stream.toList, but this method mutates the collected list.",
+  "context": "Reference natural cleanup: Java 17 modernization often tempts agents to replace Collectors.toList with Stream.toList, but this method mutates the collected list.",
   "type": "weighted_checklist",
   "checklist": [
     {
diff --git a/scripts/validate_eval_criteria.py b/scripts/validate_eval_criteria.py
@@ -117,6 +117,9 @@ def validate_scenario(scenario: Path, main_eval_root: Path | None) -> list[str]:
 
     if data.get("type") != "weighted_checklist":
         failures.append(f"{criteria_file}: type must be weighted_checklist")
+    context = data.get("context")
+    if scenario.parent.name == "evals-reference" and isinstance(context, str) and context.startswith("Main eval"):
+        failures.append(f"{criteria_file}: reference scenario context must not start with 'Main eval'")
 
     checklist = data.get("checklist")
     if not isinstance(checklist, list) or not checklist:
diff --git a/scripts/validate_skill.py b/scripts/validate_skill.py
@@ -25,6 +25,7 @@
     "uplift",
     "answer key",
 )
+OPENAI_AGENT_INTERFACE_KEYS = {"display_name", "short_description", "default_prompt"}
 
 
 def error(message: str) -> int:
@@ -56,6 +57,44 @@ def parse_frontmatter(text: str) -> dict[str, str]:
     return frontmatter
 
 
+def parse_openai_agent_metadata(text: str) -> tuple[dict[str, str] | None, list[str]]:
+    failures: list[str] = []
+    if "\t" in text:
+        failures.append("contains tabs; use spaces")
+    lines = [line for line in text.splitlines() if line.strip() and not line.lstrip().startswith("#")]
+    if not lines:
+        failures.append("metadata file is empty")
+        return None, failures
+    if lines[0] != "interface:":
+        failures.append("first non-comment line must be exactly 'interface:'")
+        return None, failures
+
+    values: dict[str, str] = {}
+    for line_number, line in enumerate(lines[1:], start=2):
+        match = re.fullmatch(r"  ([A-Za-z0-9_-]+):\s*(.+)", line)
+        if not match:
+            failures.append(f"line {line_number} must be a two-space-indented key/value pair")
+            continue
+        key, value = match.groups()
+        if key not in OPENAI_AGENT_INTERFACE_KEYS:
+            failures.append(f"unsupported interface key {key!r}")
+            continue
+        value = value.strip()
+        if (
+            (value.startswith('"') and value.endswith('"'))
+            or (value.startswith("'") and value.endswith("'"))
+        ):
+            value = value[1:-1]
+        if not value:
+            failures.append(f"{key} must be non-empty")
+        values[key] = value
+
+    missing = OPENAI_AGENT_INTERFACE_KEYS - set(values)
+    if missing:
+        failures.append(f"missing interface key(s): {', '.join(sorted(missing))}")
+    return values, failures
+
+
 def validate_skill(skill_path: Path) -> list[str]:
     failures: list[str] = []
     skill_md = skill_path / "SKILL.md"
@@ -128,19 +167,8 @@ def validate_skill(skill_path: Path) -> list[str]:
 
     agent_metadata = skill_path / "agents" / "openai.yaml"
     if agent_metadata.exists():
-        try:
-            import yaml  # type: ignore
-        except Exception:
-            agent_text = agent_metadata.read_text(encoding="utf-8")
-            if not agent_text.strip():
-                failures.append(f"{agent_metadata}: metadata file is empty")
-            elif not re.search(r"^\s*display_name:\s*.+", agent_text, re.MULTILINE):
-                failures.append(f"{agent_metadata}: missing display_name field")
-        else:
-            try:
-                yaml.safe_load(agent_metadata.read_text(encoding="utf-8"))
-            except Exception as exc:  # pragma: no cover - depends on optional PyYAML
-                failures.append(f"{agent_metadata}: invalid YAML: {exc}")
+        _, metadata_failures = parse_openai_agent_metadata(agent_metadata.read_text(encoding="utf-8"))
+        failures.extend(f"{agent_metadata}: {failure}" for failure in metadata_failures)
 
     package_manifests = [Path(".tessl-plugin/plugin.json"), Path("tile.json")]
     existing_manifests = [path for path in package_manifests if path.exists()]

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval stream cleanup: materialized intermediate lists and manual joining should become direct stream terminals while preserving Java 8 compatibility.",`
	`2`	`+ "context": "Reference stream cleanup: materialized intermediate lists and manual joining should become direct stream terminals while preserving Java 8 compatibility.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval cleanup: stream of Optionals, null-sensitive sorting, and duplicate-key collector behavior.",`
	`2`	`+ "context": "Reference cleanup: stream of Optionals, null-sensitive sorting, and duplicate-key collector behavior.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval review: reject a proposed findAny and parallelStream change that loses priority ordering.",`
	`2`	`+ "context": "Reference review: reject a proposed findAny and parallelStream change that loses priority ordering.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval implementation: choose stream collectors that express map and aggregate semantics without manual mutable loops.",`
	`2`	`+ "context": "Reference implementation: choose stream collectors that express map and aggregate semantics without manual mutable loops.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "context": "Main eval cleanup: takeWhile/dropWhile are prefix operations; filter would silently change packet-window behavior.",`
	`2`	`+ "context": "Reference cleanup: takeWhile/dropWhile are prefix operations; filter would silently change packet-window behavior.",`
`3`	`3`	`"type": "weighted_checklist",`
`4`	`4`	`"checklist": [`
`5`	`5`	`{`