Polychro v1.0.0-beta2 — "Shooner"

⛵ A schooner is fast and lean where a ketch is sturdy — and Polychro's beta2 follows the same path as its sibling Ikanos release: no flagship feature, but the engine now understands Markdown and HTML structure the same way it understands YAML. Ruleset diagnostics on projected $.document.blocks[*] / $.document.nodes[*] finally carry a real source location instead of collapsing to the top of the file, the CI pipeline is renamed and widened to the Go/Node/Python SDKs, and Dependabot now watches every dependency. A maintenance release that pays down infrastructure debt before the next feature push.

What is Polychro?

Polychro is a deterministic linting engine for spec-driven development. It validates semi-structured specifications — YAML, JSON, XML, Markdown, and HTML — through composable layers (well-formedness, schema-model, ruleset, and format-aware validation) in a single embeddable pipeline with sub-second latency.

Built on Spectral's shoulders. Polychro adopts Spectral's given/then ruleset grammar — the de facto standard for API governance rules — and extends it into a fully self-contained, polyglot engine. Where Spectral requires Node.js and is narrowly focused on OpenAPI, Polychro runs as a single JVM binary with no external runtime, supports custom rule functions in JavaScript, Python, and Groovy, and lints YAML, JSON, XML, Markdown, and HTML in the same pipeline.

💡 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.

This v1.0.0-beta2 release builds on v1.0.0-beta1 ("Ketch") with a focus on structural correctness for non-YAML formats and CI/quality infrastructure: rulesets can now traverse a real Markdown/HTML document tree instead of a raw text blob, the build pipeline is renamed and hardened, and dependency updates are automated. No breaking changes to the SPI or ruleset grammar.

✨ Highlights

🌳 Markdown & HTML Ruleset Projection — DocumentEnricher SPI (#38)

The core change of beta2: the generic ruleset engine (RulesetValidator) previously only ever saw a raw TextNode for markdown and html, so JSONPath given expressions matched nothing and any ruleset scoped to those formats silently produced zero diagnostics. The built-in MarkdownValidator / HtmlValidator already projected internally, but that structure never reached the ruleset engine.

• New DocumentEnricher SPI in polychro-api — Document.fromString(...) discovers and delegates to a format-specific enricher via ServiceLoader when one is on the classpath, degrading gracefully to the previous TextNode behavior otherwise (f3a1583)
• MarkdownDocumentEnricher / HtmlDocumentEnricher parse and project via the existing MarkdownParserFacade+MarkdownProjector / HtmlParserFacade+HtmlProjector, preserving the raw source under the raw.content metadata key and registered via META-INF/services (e77c8b4, #38)
• RulesetValidatorFactory now advertises markdown and html in supportedFormats(), so rulesets can target $.document.blocks[*] (Markdown) and $.document.nodes[*] (HTML) with a resolved SourceRange
• MarkdownValidator.extractRawContent and HtmlValidator.validate read raw.content from metadata first, keeping their existing line/parser-based checks working against enriched documents (fa45b3f)
• GraalVM native-image config extended with reflect-config.json entries for both enrichers and a resource-config.json pattern for the DocumentEnricher services file — without it, ServiceLoader silently drops the providers in the native binary with no exception, and any ruleset targeting the projected structure would produce zero diagnostics instead of the expected ones (f1bc9cf)
• Two new native-image smoke tests (Markdown + HTML) added to publish-cli-bin.yml, asserting a deliberate rule violation actually fires against the projected structure in the real binary — closing a gap the existing exception-only checks could not catch
• LintCommandTest updated: since polychro-cli has polychro-markdown/polychro-html as compile dependencies, Document.fromString always returns the projected structure for these formats now, so the two tests asserting the old raw-TextNode fallback were rewritten against the actual projected shape (f7ccaf4)

🌙 CI / Quality Gate Overhaul

• ci.yml removed and replaced by a renamed quality-gate.yml, now also running the Go, Node.js, and Python SDK unit tests as part of every push/PR build, not just the Java modules (#86, 8ea6d51)
• Coverage/quality badges no longer publish through a personal Gist — they are generated as JSON and pushed to a dedicated badges branch, read directly via raw.githubusercontent.com (c0b3b4a, f82186e)
• GitHub Dependabot enabled for Maven and GitHub Actions dependencies, weekly checks (bbc62d5)
• CODEOWNERS added, defaulting the whole repository to @naftiko/engineering
• Nightly quality-gate workflow hardened: Gitleaks binary now installed into /tmp instead of the working directory, and the workflow gained pull-requests: write permission for its automated summaries

📚 Documentation

• README repositioned: a sharpened lead sentence now states Polychro's core differentiator — linting in the coding agent's inner loop rather than handing off to a CI gate — the leading horizontal logo was dropped so the value proposition leads, and the architecture diagram was widened from 700 to 800 px (#73, 7e7607d)
• All documentation links repointed from the retired 1.0.0-alpha4 docs path to 1.0.0-beta1, and "upcoming alphas" reworded to "upcoming releases" in the Roadmap section
• golden-repo-naftiko rename propagated across AGENTS.md and the agents-shared skill-discovery instructions, following the golden repo's rename on GitHub (3cc3a29, c541713)

⚠️ Known Issues & Limitations

• JSON and XML source ranges — Markdown and HTML now carry real ruleset SourceRanges, but JSON (#34) and XML (#35) ruleset diagnostics still report SourceMap.NONE; tracked under the source-ranges epic (#38)
• Tutorial known limitations carried over from beta1: non-string-key false positive on quoted HTTP status codes (#5) and .polychro.yml schema config not consumed in Step 4 (#6)
• CLI pre-built binary installation — running the binary directly is not straightforward on macOS (Gatekeeper quarantine: xattr -dr com.apple.quarantine) or Windows (SmartScreen warning, unsigned binary). Workaround: run via java -jar polychro.jar
• polychro-rulesets JaCoCo coverage — pre-existing gap on main; coverage gate not yet enforced for this module
• Checkov — requires a local Checkov installation; not bundled in the binary
• CLI pre-built binaries available for macOS ARM64, Linux AMD64, Linux ARM64, and Windows AMD64

🔢 By the Numbers

• 16 commits merged since v1.0.0-beta1
• 33 files changed, +908 / −123 lines
• 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @eskenazit — DocumentEnricher SPI end-to-end (Markdown/HTML projection, native-image reflect/resource config, regression-guard smoke tests) (#38), golden-repo-naftiko rename propagation, design-doc vocab rename
• @farah-t-trigui — Go/Node/Python unit tests in the quality gate (#86), Dependabot setup, Gist-to-badges-branch migration
• @jlouvel — README repositioning and doc-link refresh to beta1 (#73)
• @jeremnaf — release coordination

Full Changelog: v1.0.0-beta1...v1.0.0-beta2