Ikanos v1.0.0-alpha4 — "Yawl"

Ikanos v1.0.0-alpha4 — "Yawl" ⛵ — Release Notes

⛵ A yawl is a small, nimble two-masted boat — and the fourth Alpha is exactly that:
a tighter, steadier release that consolidates the rigging. After alpha3's big rename and
feature push, alpha4 hardens observability (end-to-end trace/span correlation in logs),
ships a self-improving agent bugfix skill, automates a nightly quality gate, and locks
down the version-sync machinery so the spec never drifts again.

What is the Naftiko Framework?

The Naftiko Framework — branded Ikanos — is the first open-source engine for
Spec-Driven Integration.
Capabilities are declared entirely in YAML — no Java, no code generation, no compilation
step. The engine reads the spec at startup and immediately serves it as a multi-protocol
server: MCP, Skill, REST, and Control. The spec is the artifact and the
runtime contract.

Ikanos comes from the Greek ικανός — capable.

This v1.0.0-alpha4 release builds on v1.0.0-alpha3 ("Trimaran") with a focus on
operational maturity: log/trace correlation, CI/CD automation, and drift-proofing the
spec-version pipeline. It is deliberately a consolidation release — no breaking changes to
the capability schema beyond the version bump.

🌐 Ecosystem

Polychro — Spec Linting for Ikanos Capabilities

Polychro remains the companion spec linting engine
for the Ikanos ecosystem. It validates Ikanos capability files against rulesets declared in
YAML, surfacing diagnostics as SARIF, JSON, or LLM-native output — directly inside your
editor, CI pipeline, or AI agent. See the Polychro release notes for its own changelog.

✨ Highlights

🔭 End-to-End Trace Correlation in Logs (#548)

Logs emitted by the engine now carry the active OpenTelemetry trace and span IDs, so a log
line can be joined directly to its distributed trace:

• SLF4J MDC is populated with trace_id / span_id on MCP and REST requests
• New logback.xml ships an OTel log appender plus a console pattern that prints
  traceId=… spanId=… on every line
• Least-privilege MDC export — only the correlation keys Ikanos owns (trace_id,
  span_id) are forwarded to the OTel pipeline, never arbitrary third-party MDC data an
  embedding application may set
• Cross-cutting fix applied to all three server adapters — REST, MCP, and the Skill
  server resource — not just the two in the original report (#548) ✅

🤖 Agent & Contributor Experience

• New bimodal bugfix skill — a guided Java/Maven bugfix workflow with a self-review
  quality gate: Mode A (fresh issue → reproduce → failing test → fix → PR) and Mode B
  (resume an existing PR / address review feedback) (#554)
• The skill is repo-agnostic (derives owner/repo from the working directory) and
  scoped to Java/Maven repositories
• Pre-Code Checklist hardened with a round-trip-lookup rule (#563) and a
  "scan loops must reach the boundary" rule
• pr-review skill repointed to the shared agents-shared capability in the
  code-standards golden repo — the per-repo copy and its helper scripts are removed,
  eliminating duplication
• AGENTS.md / CONTRIBUTING.md self-improvement loop: cross-cutting-fix rule, Mode B
  handoff learnings, softened "open an issue first" rule with an anti-accretion guardrail,
  and expanded Windows file-I/O (read/inspect encoding) rules

🌙 Nightly Quality Gate & CI/CD Automation

• Nightly orchestrator — a scheduled trigger dispatches the full quality gate against
  every open PR branch and main each night, catching drift between PR-time and merge-time
• New nightly-quality-gate.yml workflow with a complete test plan and status badges
• Docker Hub publishing wired for the engine image
• Maven publishing hardened with a Microcks setup step in publish-maven.yml
• Engine image build adds the coverage and tunnel-ziti modules to the Dockerfile
• Tutorial example validation points at a local Microcks instance instead of
  mocks.naftiko.net, removing an external network dependency from CI

🧷 Alpha4 Migration & Drift Hardening

The hop from alpha3 to alpha4 exposed gaps in the version-sync machinery — all closed:

• 26 YAML/JSON test fixtures and 6 inline Java text blocks still pinned to older versions
  were migrated (two CLI tests had never been migrated past alpha1/alpha2)
• Inline YAML in Java tests now injects the spec version dynamically via
  VersionHelper.getSchemaVersion() (reads the Maven-filtered version.properties), so
  future bumps are picked up automatically — the published schema JSON keeps a real version
  const and stays a ready-to-consume artifact
• The rule is now documented in AGENTS.md (Test Writing Rules) and CONTRIBUTING.md
  (handling the spec version), with scripts/sync-ikanos-version.py as the single source for
  fixture paths
• The published ikanos-schema.json was re-encoded to clean UTF-8 (em-dash mojibake
  removed) and its $id / version const bumped to 1.0.0-alpha4
• aggregate added to the GraalVM reflect config so the native CLI image resolves it

📚 Documentation

• README and in-repo documentation links now point to the Shipyard portal
  (https://shipyard.naftiko.io)
• Architecture diagram widened to 700px for readability
• PULL_REQUEST_TEMPLATE.md gains a dedicated documentation section
• Eclipse IDE files (.settings, .classpath, .project) added to .gitignore

⚠️ Known Issues & Limitations

• Native CLI binary crashes on serve and validate — the pre-built native binaries
  (alpha4) are missing Restlet and part of the networknt schema-validator classes from the
  GraalVM reflect-config.json, so ikanos serve (HTTP connector / Restlet Finder) and
  ikanos validate (MaxLengthValidator) fail with ClassNotFoundException /
  NoSuchMethodException. Workaround: run the JVM jar instead — java -jar ikanos.jar serve …
  (the JVM needs no reflect-config). Fix tracked in
  #581, to ship in alpha4.1.
• CLI pre-built binary installation — running the CLI binary directly is not
  straightforward on macOS (Gatekeeper quarantine requires xattr -dr com.apple.quarantine
  or system approval) and on Windows (SmartScreen warning, unsigned binary). Workaround: run
  via java -jar ikanos.jar from the JAR instead (#281)
• Reverse tunnel remains declarative-only in the schema — capabilities that declare
  tunnel: parse and validate today, but the engine still dials the public baseUri
  directly until the embedded tunnel feature is enabled. Use the sidecar pattern from the
  Reverse Tunnel guide for production today.
• CLI pre-built binaries available for macOS ARM64, Linux AMD64, Linux ARM64, and Windows AMD64

🔢 By the Numbers

• 36 commits merged since v1.0.0-alpha3
• 138 files changed, +2,344 / −2,117 lines
• 4 contributors

🙏 Contributors

Huge thanks to the team for shipping this release:

• @eskenazit — MDC trace/span correlation (#548), bimodal
  bugfix skill (#554), pr-review repoint to agents-shared, alpha4 migration & drift
  hardening, AGENTS.md / CONTRIBUTING.md governance
• @farah-t-trigui — nightly quality-gate orchestrator,
  Docker Hub & Maven publishing, Microcks CI integration, status badges
• @jeremnaf — CLI fixes and native build support
• @jlouvel — engine image modules, GraalVM reflect config,
  documentation & Shipyard links, release coordination

Full Changelog: v1.0.0-alpha3...v1.0.0-alpha4