weiqingy opened a new issue, #968: URL: https://github.com/apache/flink-agents/issues/968
### Background `docs/yaml-schema.json` is exported from the Pydantic specs (`python -m flink_agents.api.yaml.specs`), and two checks already keep it honest: `python/flink_agents/api/yaml/tests/test_specs.py:377` asserts it matches the Pydantic export, and `api/src/test/java/org/apache/flink/agents/api/yaml/spec/SchemaParityTest.java:52` asserts it matches the Java POJOs. The coding-agent skill added in #918 ships a third copy so it can answer YAML questions offline, plus a record of where that copy came from: - `dev/agent-skills/flink-agents-dev/assets/yaml-schema.json`, byte-identical to `docs/yaml-schema.json` today - `dev/agent-skills/flink-agents-dev/assets/yaml-contracts.yaml`, whose `main` contract records `blob_sha: 183cc7ac800cf97d030b75b166ea8146368747d5` At `bc55d97e` all three agree. `git rev-parse HEAD:docs/yaml-schema.json` returns that same SHA. ### The gap Neither existing check extends past `docs/yaml-schema.json`, and nothing regenerates the bundled copy. Regenerating the schema and forgetting the skill assets leaves no failing test, so the drift is only found by someone reading both files. Two distinct things go stale, with different consequences. The copy itself goes stale, and an agent consulting it is then taught a schema the repository no longer has. That is the failure the skill exists to prevent. The recorded `blob_sha` also goes stale, which is the quieter half. `SKILL.md:45` tells agents the bundled main schema "describes only the repository revision that published this skill", and `references/local-development.md:62` says a source checkout should fall back to the bundled schema "only when they describe the same revision". Both instructions are decided by that SHA, so a stale value does not just lag. It asserts a provenance that is false, and it does so in the exact place an agent goes to decide whether the bundled copy is safe to trust. ### Proposal A dependency-free check under `tools/`, run from the existing `lint` job next to `Check AGENTS.md freshness`, asserting that the bundled copy and the recorded `blob_sha` both match `docs/yaml-schema.json`. This mirrors `tools/check-agents-md.py`, which guards the same class of hand-copied fact. The failure message should print the two edits needed, since the fix is mechanical and the person hitting it is usually mid-way through an unrelated schema change. ### Out of scope `dev/agent-skills/flink-agents-dev/assets/yaml-schemas/release-0.3.0.json` pins ref `release-0.3.0` and is expected to differ from the working tree. Only the unversioned `main` contract should be checked. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
