Today we’re shipping Polychro v1.0.0-beta1 — the first release stable enough for real linting. After two alpha releases that composed the pipeline and sharpened diagnostic precision, beta1 makes JavaScript ruleset functions work reliably in the native binary, fixes the functionsDir resolution bug that broke polyglot rules in non-trivial setups, and ships the first complete tutorial — verified against the beta1 CLI itself.
But before the changelog, it’s worth revisiting why Polychro exists in the first place.
The Problem: The Linter Lives in the Wrong Place
The first wave of spec linting put the linter at the CI gate. That made sense when a human wrote a spec once, opened a pull request, and waited for a review. It makes far less sense now that a coding agent is generating specs in a tight loop — capabilities, MCP manifests, CRDs, instruction files, OpenAPI — dozens of times a session. The complaints are now in, and they rhyme:
- Too far right. A CI-gated linter only speaks up after the agent has produced a spec, committed it, and opened a PR. By then the bad spec has already cost a round trip. The feedback the agent needs in the same turn arrives minutes — or a reviewer — later.
- Node.js in the hot path. Spectral is the de facto standard for API governance rules, but it requires a Node.js runtime and a 2–5 second subprocess cold start. That’s an eternity inside an agent’s generate-validate-retry loop.
- OpenAPI-only. Legacy linters were built to see OpenAPI. The flood of AI-generated specs is not just OpenAPI — it’s arbitrary YAML, JSON, XML, Markdown, and HTML that no OpenAPI-shaped linter treats as a first-class document.
- A pile of tools to stitch together. Meta-linters like Super-Linter and MegaLinter bundle dozens of third-party tools in a large Docker image, each with its own config. That’s a platform dependency, not an inner-loop guardrail.
None of these are intrinsic to linting. They’re intrinsic to running someone else’s linter, at someone else’s stage, on someone else’s runtime.
The Polychro Answer: Shift Linting All the Way Left
Polychro is the open-source AI linter for spec-driven development. It lets your coding agent lint as it builds — in-process, multi-format, and agent-native — instead of handing the spec off to the one linter gating your CI pipeline. It reads a specification — YAML, JSON, XML, Markdown, or HTML — and tells you what’s wrong with it in a single, fast pass: structural mistakes, schema violations, broken conventions, and security anti-patterns. One binary, one config, one diagnostic format.
The key insight is that the linter belongs inside the agent’s inner loop, not at the CI gate. Polychro runs as a self-contained native binary with sub-second cold start, or in-process inside any JVM — no Node.js runtime, no subprocess startup — fast enough to sit inside a generate-validate-retry loop and catch a bad spec at agent speed, before it ever reaches a pull request. It’s built on Spectral’s shoulders — it adopts the given/then ruleset grammar teams already know — and extends it into a fully self-contained, polyglot engine that lints far more than OpenAPI.
Polychro is designed to work alongside Ikanos — validating capability specs before they reach the runtime — but it is fully standalone and works with any YAML, JSON, XML, Markdown, or HTML document.
What’s New in Beta 1
🔧 Native CLI — JavaScript Ruleset Functions Now Work
The most impactful fix of beta1: JavaScript ruleset functions now execute correctly in the native binary on all platforms. Earlier builds packaged the runtime in a way that prevented the JavaScript engine from registering, so polyglot rules written in JavaScript silently failed to load in the standalone executable.
Beta1 fixes how the native binary is assembled so the JavaScript engine registers correctly. Validated on macOS ARM64: the native binary now executes JS ruleset functions and emits identical JSON diagnostics to the JVM jar.
🗂️ Polyglot functionsDir Resolution Fixed
functionsDir in .polychro.yml now resolves relative to the ruleset file, not relative to the process working directory. Running polychro lint from any directory now produces consistent results, and the JavaScript function files referenced in rulesets are discovered and loaded correctly regardless of where the CLI is invoked from.
📖 Track 1 YAML Tutorial — Complete & Verified
The first complete Polychro tutorial ships with beta1, built around the Modern Maritime Registry API and covering seven progressive linting steps. Each step introduces one defect at a time — exercising well-formedness, schema validation, built-in ruleset rules, and polyglot JS functions in turn. Every example was run against the freshly built polychro 1.0.0-beta1 binary, so the expected output is the real per-step output, not a hypothesis. A new tuto_writer agent drives tutorial authoring, keeping the examples aligned with real engine behaviour.
🤝 Polyglot Function Hardening
The polychro-ruleset-polyglot module was hardened for production: the function loader and rule-function runtime picked up improved JavaScript doc handling, with new unit tests covering the full polyglot function lifecycle.
🌙 CI & Quality Automation
Slack notifications on nightly failures now page the team when a quality-gate run breaks, the nightly workflow was fixed, and the macOS runner was pinned to work around a GitHub Actions runner transition.
📚 Documentation
The README was restructured around reader personas — agent builder, platform operator, spec author — for faster onboarding, with links tightened and pointed at the live Shipyard docs.
A Deliberate Signal Toward Stability
Beta1 introduces no breaking changes to the SPI or the ruleset grammar — a deliberate signal that the engine is maturing toward stability. The layered pipeline is unchanged: well-formedness → schema-model → ruleset → format-aware validation, all producing the same unified Diagnostic format. Your Spectral rulesets keep working, your custom rule functions — in JavaScript, Python, Groovy, or Java — keep working, and the same config lints YAML, JSON, XML, Markdown, and HTML in one pass.
A few limitations remain, all documented: non-YAML source ranges still report SourceMap.NONE pending follow-up; the pre-built binaries need one unquarantine step on macOS and Windows (or run via java -jar); and two tutorial edge cases are noted with fixes planned.
By the Numbers
21 commits merged since v1.0.0-alpha4. 30 files changed, +1,324 / −270 lines. 4 contributors.
The engine is now stable enough for real integrations. Polychro comes from the Greek poly + chroma — many colours, for the many spec formats it lints in one pass.
