SotuRail v1.5.0 - Verified Control Plane Foundation

SotuRail v1.5.0 ? Verified Control Plane Foundation

v1.5 turns SotuRail's context rails into a workspace-bound engineering control plane. It hardens filesystem and raw-log boundaries, makes artifact lineage/freshness explicit, modernizes MCP, and ships deterministic governance, contract, readiness, and execution-envelope foundations.

Highlights

• Canonical WorkspaceGuard, Artifact Registry/Store/Envelope, and Workspace Fingerprint.
• Capability Registry/Epochs, Run Manifest, Change Contract, NativeMinimal governance, Dual Gate, and exact-digest Execution Envelope.
• Hard-budget shared context artifacts and workspace-bound evidence/knowledge freshness.
• Official typed MCP SDK with modern protocol and legacy negotiation smoke coverage.
• Node 22/24 baseline, CodeQL, full audit, CycloneDX SBOM, checksums, release manifest, and build/SBOM attestations.

Security fixes

• Closed caller-controlled MCP raw-log authorization; MCP disclosure is always redacted.
• Rejected traversal, absolute-path escape, symlink escape, sensitive paths, and Windows boundary edges through WorkspaceGuard.
• Added raw sensitivity, content fingerprint, retention, inspection, doctor, and purge lifecycle metadata.
• Added architecture drift checks for raw bypasses, MCP mapping, workspace guards, atomic stores, runtime baseline, and native metadata.

Integrity and evidence

Critical JSON persistence is atomic and JSONL tail interruption is recoverable. Knowledge topics use source-derived IDs and remove residue after rename/delete. Evidence records a workspace fingerprint and becomes stale after workspace changes rather than silently retaining verified status.

Governance and contracts

The offline NativeMinimal provider validates known capabilities and required approvals. Authority and readiness are independent gates and both must pass. Execution is attested only when its payload digest equals the evaluated digest. AGT/ACS is a tested fail-closed adapter boundary, not an advertised integration.

MCP compatibility

The modern server uses the official v2 SDK and stable 2026-07-28 protocol path. Legacy negotiation remains covered for existing hosts. Tool schemas are strict and tools map to canonical capability IDs. Arbitrary shell is not exposed.

Documentation and roadmap

New current-state documents cover the verified control plane, artifacts/lineage, governance, context, contracts/verification, providers, threat model, benchmarking, v1.5 commands, and migration. The roadmap is now dependency-ordered and the master implementation tracker retains honest partial/deferred states.

Migration and deprecation

• Node.js 20 support is removed; use Node 22 or 24.
• MCP callers must remove allow_raw; exact disclosure is local CLI-only.
• Regenerate old artifacts when freshness/schema checks report them stale.

See Migration to v1.5.

Compatibility

The existing CLI rails and TypeScript fallback remain. Modern and legacy MCP negotiation are tested. The optional native crate remains optional and now shares release/license metadata with the npm package.

Known limitations

• The architecture report retains four non-blocking boundary warnings for large legacy commands/core-to-command imports.
• SotuRail is not a sandbox; host and OS enforcement remain external.
• Provider results and generated artifacts are not automatically human-approved or runtime-verified.
• General schema migration/rollback and evidence receipts are not present in v1.5.

Deliberately deferred

AGT/ACS live integration, SQLite/FTS index, structural graph adapters, Decision Graph, full evidence receipts, temporal/outcome brain, vector backend, runtime orchestration/Conductor, Tauri UI, integration broker, and media/browser providers.

Verification

npm run build
npm run typecheck
npm test
npm run docs:check
npm audit
node dist/cli.js mcp smoke
node dist/cli.js self architecture --check
cargo test --manifest-path native/soturail-native/Cargo.toml
npm run release:check
npm run release:artifacts

Published release verification

• Release commit: 0ae5a510d8cc2ed68d9673ec631b601304162e75 on main.
• Local verification: 159/159 tests passed; release preflight passed; npm audit reported 0 vulnerabilities.
• CI: Node.js 22 and 24 passed on Linux, macOS, and Windows, including build, typecheck, tests, docs, MCP smoke, architecture checks, audit, and Rust tests.
• Security: dependency audit and CodeQL passed.
• Release assets: npm tarball, CycloneDX SBOM, SHA-256 checksums, and release manifest.
• GitHub build provenance and SBOM attestations are generated by the tag workflow.
• npm publication is intentionally pending registry authentication; the package remains version-compatible for later publication as 1.5.0 without another tag.

SotuRail v1.1.0

SotuRail v1.1.0

SotuRail v1.1.0 adds Host Compatibility Rail 1.0: host-aware exports, a richer compatibility matrix, per-host doctor reports, read-only MCP host manifests and practical docs for OpenCode, Antigravity, Gemini-compatible and DeepAgents-style handoffs.

Added

• soturail agents matrix --json now preserves soturail.agents.matrix.v1 and adds contractId: soturail.agent-host-matrix.v1.
• soturail agents doctor --host <host> writes .soturail/agents/<host>/doctor.json and .md.
• soturail agents doctor --all --json writes .soturail/agents/doctor-summary.json and .md.
• soturail mcp resources host-manifest --host <host> [--json] writes read-only host manifests.
• soturail agents export --agent gemini-legacy supports Gemini legacy/compatible handoffs.
• OpenCode exports include AGENTS.md and context packs.
• Antigravity exports include high-priority experimental transition guidance.
• DeepAgents/deepagents-js exports include role-pack.md and subagents.md.

Changed

• Default agent exports are mirrored to .soturail/agents/<host>/ and .soturail/exports/agents/<host>/.
• Agent reports support OpenCode, Antigravity, Cursor, Gemini legacy and DeepAgents-style targets.
• Docs now include host matrix schema, export contract, MCP host manifest, OpenCode tutorial and media guidance.
• README and ROADMAP now mark v1.1.0 Host Compatibility Rail as delivered.

Safety

• No cloud telemetry.
• No server requirement.
• No destructive MCP tools.
• No shell execution through MCP.
• No provider lock-in.
• TypeScript fallback remains mandatory.
• Experimental hosts are labeled honestly; OpenCode is generic-compatible, Antigravity is experimental, and DeepAgents exports are role/context artifacts only.

Verification

Run before publishing:

npm run typecheck
npm run build
npx vitest run tests/v110.test.ts
npx vitest run tests/v100.test.ts
npm test
npm run release:check
node dist/cli.js agents matrix --json
node dist/cli.js agents doctor --all --json
node dist/cli.js mcp resources host-manifest --host codex --json
node dist/cli.js report agent --agent opencode

Known Limitations

• Host compatibility remains export/report/manifest oriented; SotuRail does not become a host runtime.
• Antigravity support remains prompt/context only until a stable Google-local project config surface is documented.
• OpenCode support is generic-compatible and does not claim full host-native integration.
• DeepAgents exports are role packs and subagent notes only; no runtime dependency is installed.

SotuRail v1.0.1

SotuRail v1.0.1

Changed

• Updated package and repository licensing metadata to Apache-2.0.
• Aligned README license badge and license section with Apache-2.0.
• Aligned docs/licensing-strategy.md with the Apache-2.0 licensing decision.

Notes

This is a small metadata/documentation release after v1.0.0. No runtime behavior changes are intended.

SotuRail v1.0.0

SotuRail v1.0.0 - Release Notes

SotuRail v1.0.0 freezes the first stable local Context OS surface for AI coding agents.

Install

npm install -g soturail@1.0.0
soturail --version

Highlights

• Stable command surface for status, reports, dashboard, observability, Project Brain, evaluation, benchmarks, native candidate reporting, baseline snapshots, release checks, workflow, harness, diagrams, agents and read-only MCP report resources.
• Strict schema checks with soturail self schemas --check --strict.
• Strict v1 readiness checks with soturail self readiness --v1 --strict.
• Strict release gates with soturail release check --strict.
• Clean-code maintainability checks with soturail self code-health.
• Architecture boundary checks with soturail self architecture --check.
• Agent host compatibility matrix with soturail agents matrix.
• v1 docs for quickstart, schema contracts, stable command surface, agent hosts, clean code and architecture boundaries.

Stable Boundaries

• All reports remain local artifacts.
• No cloud telemetry or dashboard server is required.
• MCP report resources are read-only.
• TypeScript fallback remains mandatory.
• Native acceleration remains optional and benchmark-gated.
• Experimental rails remain available but are not part of the v1 stable contract until promoted.

Validation

• npm run typecheck
• npm run build
• npm test
• npm run release:check
• soturail self schemas --check --strict
• soturail self readiness --v1 --strict
• soturail self code-health
• soturail release check --strict

Links

• npm: https://www.npmjs.com/package/soturail
• GitHub: https://github.com/Soturine/soturail

SotuRail v0.10.1

SotuRail v0.10.1

v0.10.1 is a stability release for the local reports milestone. It fixes JSON validity concerns, improves report/dashboard/observability ergonomics, polishes benchmark/native/baseline evidence and adds v1.0 readiness scaffolding without breaking existing public commands.

Highlights

• soturail status --json is hardened as valid JSON output parseable by JSON.parse.
• Local JSON artifacts are covered by stricter status/report/MCP/bench/native/baseline contract tests.
• soturail self schemas --check writes schema compatibility reports under .soturail/schemas/.
• soturail self readiness --v1 writes candidate v1 readiness reports under .soturail/readiness/.
• Report doctor, diff, redaction output and agent reports now provide clearer next commands.
• Dashboard doctor validates local JSON data and still requires no server or external assets.
• Observability collection skips duplicate local artifact events and writes clearer summaries.
• Benchmark/native/baseline output now repeats the TypeScript fallback and benchmark-gated policy.
• Project Brain suspect/stale counts are framed as evidence freshness warnings, not automatic code failures.

Commands Added

soturail self schemas --check
soturail self schemas --check --json
soturail self readiness --v1
soturail self readiness --v1 --json

Commands Improved

soturail status --json
soturail status --agent
soturail report latest
soturail report doctor
soturail report redact
soturail report diff
soturail report agent --agent codex
soturail dashboard doctor
soturail obs collect
soturail obs summary
soturail bench report
soturail bench compare
soturail native candidates
soturail native doctor
soturail self baseline --check
soturail release check

Artifacts Added

.soturail/schemas/check.json
.soturail/schemas/check.md
.soturail/readiness/v1.json
.soturail/readiness/v1.md
docs/stable-command-surface.md
docs/deprecation-policy.md
docs/migration-v1.md

Stability And Safety

• Every main JSON artifact is expected to be parseable.
• Release preflight now checks local JSON artifacts when present.
• Report redaction prints finding kinds and counts without leaking secret values.
• Normal package hashes and integrity hashes are not redacted unless they look credential-like.
• No cloud, telemetry upload, server requirement, destructive MCP tools or breaking command removals were added.

Known Limitations

• v1.0 readiness is a draft check, not a final stability guarantee.
• self schemas --check validates top-level schema compatibility; it is not a full JSON Schema validator.
• High Project Brain suspect/stale counts still need human review through brain stale --repair-plan.
• Native acceleration remains optional and benchmark-gated; TypeScript remains the default fallback.

Upgrade Notes

npm install -g soturail@0.10.1
soturail status --json
soturail report build
soturail self schemas --check
soturail self readiness --v1

SotuRail v0.10.0

SotuRail v0.10.0

v0.10.0 adds local reports, unified status, observability timeline, static dashboard artifacts, agent-readable reports, GitHub summary export, redaction checks and read-only MCP report resources.

Added

• soturail status --json|--md|--agent for a unified local status model.
• soturail report build, report latest, report export, report doctor, report redact, report github-summary, report agent and report diff.
• soturail dashboard build|open|doctor for static local dashboard artifacts.
• soturail obs collect|summary|timeline|export for local observability events.
• Read-only report resource manifest through soturail mcp resources report.
• Agent-readable report exports for Codex, Claude, Gemini and generic hosts.
• Local report redaction and safety checks for obvious credential patterns.
• llms.txt with factual documentation entry points.

Changed

• Release preflight now includes report safety and optional status/report/dashboard/observability/MCP evidence gates.
• Workflow evidence now references unified status, local reports, static dashboard, observability and MCP report resource artifacts when present.
• README and docs now describe local reports, dashboard, observability, report redaction and MCP report resources.

Security

• Reports and dashboards are local artifacts. SotuRail does not upload telemetry and does not require a dashboard server.
• Dashboard output uses plain local HTML/CSS and rejects external script/CDN references in dashboard doctor.
• MCP report resources are read-only and do not expose shell execution or report mutation.

SotuRail v0.9.0

SotuRail v0.9.0 - Release Notes

Install

npm install -g soturail@0.9.0
soturail --version

Highlights

• Added Benchmark Rail 2.0 reports with soturail bench list, bench run --suite <suite>, bench compare and stable .soturail/bench/latest.* output.
• Added benchmark categories for Project Brain, reducers, JSONL, range hashing, file scanning, workflow evidence and release preflight.
• Added soturail native candidates, native status, improved native doctor and native compare so native work is classified before any acceleration claim.
• Added soturail self baseline --check|--zip|--bundle|--pack for clean source, history and package snapshots.
• Release and workflow evidence now reference benchmark, native candidate and baseline reports when present.
• Added docs for benchmark-gated native policy, baseline snapshots and the deferred parser/graph seed.

Safety

• TypeScript fallback remains mandatory and default.
• Rust/native remains optional.
• Normal npm install does not require Rust, Cargo or native build tools.
• SotuRail does not claim native speedups unless a local benchmark report proves them.
• Parser/graph work is documented as a future seed, not promoted as a mandatory runtime.

Validation

• npm run typecheck
• npm run build
• npm test
• npm run release:check
• node dist/cli.js bench run --suite brain
• node dist/cli.js native candidates
• node dist/cli.js self baseline --check

SotuRail v0.8.1

SotuRail v0.8.1 - Release Notes

Install

npm install -g soturail@0.8.1
soturail --version

Highlights

• Polished Project Brain stale detection with source-range relocation events.
• Added soturail brain consolidate --dry-run for duplicate claim grouping.
• Added soturail brain stale --repair-plan and soturail brain doctor --repair-plan.
• Improved agent briefs with verified/suspect/stale separation, section limits, source references and recovery pointers.
• Made soturail rules from-brain safer by excluding stale/suspect claims from active rules.
• Expanded the brain evaluation suite with v0.8.1 quality cases.

Safety

• Repair plans are guidance only. SotuRail does not auto-edit code, docs or claims.
• Project Brain remains local and deterministic: no LLM calls, embeddings, cloud service or network-required tests.
• Native/performance work remains benchmark-gated and TypeScript fallback remains mandatory.

Validation

• npx vitest run tests/v081.test.ts
• npx vitest run tests/v080.test.ts
• npm run typecheck
• npm run build
• npm test
• npm run release:check
• git diff --check
• node dist/cli.js brain consolidate --dry-run
• node dist/cli.js brain stale --repair-plan
• node dist/cli.js brain doctor --repair-plan
• node dist/cli.js eval run --suite brain

Links

• npm: https://www.npmjs.com/package/soturail
• GitHub: https://github.com/Soturine/soturail

SotuRail v0.8.0

SotuRail v0.8.0 - Release Notes

Install

npm install -g soturail@0.8.0
soturail --version

Highlights

• Added Verified Project Brain storage under .soturail/brain/.
• Added JSONL records for claims, decisions, bugs, gaps, rules and stale events.
• Added JSON materialized views for project profile, architecture, index, freshness and doctor reports.
• Added soturail brain init, scan, profile, recall, stale, doctor and export.
• Added Reverse Specification Rail commands for local scan, claims, specs, gaps and agent handoff export.
• Added soturail rules from-brain and soturail rules doctor.
• Added soturail eval run --suite brain.
• Added agent-safe Project Brain briefs for Claude, Codex, Gemini, Cursor and Generic hosts.

Safety

• No cloud services, embeddings, external LLM calls or network-required tests.
• Brain exports include source references and stale/suspect warnings.
• Approved memory remains the only memory path suitable for agent export.
• Brain-derived rules are advisory until reviewed.

Validation

• npx vitest run tests/v080.test.ts
• npx vitest run tests/v070.test.ts
• npm run typecheck
• npm run build
• npm test
• npm run release:check
• git diff --check
• node dist/cli.js brain scan
• node dist/cli.js reverse scan ./src
• node dist/cli.js eval run --suite brain

Links

• npm: https://www.npmjs.com/package/soturail
• GitHub: https://github.com/Soturine/soturail

SotuRail v0.7.0

SotuRail v0.7.0 - Workflow, Harness And Diagram Rails

SotuRail v0.7.0 deepens the local workflow layer. It adds Workflow Rail 2.0 phases, Harness Rail integration, Diagram Rail commands, .spec.md visual contracts and release evidence that points to the new docs/releases/ release-note source.

Added

• Added soturail workflow setup.
• Added title-based soturail workflow plan "Task title" for Workflow Rail 2.0 plans.
• Added soturail workflow work, soturail workflow review --all, soturail workflow verify and soturail workflow diagram <id>.
• Added deterministic review perspectives for security, docs, tests, release, context and agent readiness.
• Added soturail diagram init, soturail diagram new <feature>, soturail diagram audit <file>, soturail diagram validate and soturail diagram from-workflow <id>.
• Added generated .spec.md visual contracts with required nodes, transitions, evidence links, validation checklist and known gaps.
• Added v0.7.0 tests for release-note paths, workflow phases, harness doctor integration, diagram commands and evidence contents.

Changed

• Moved repository release notes from root-level RELEASE_NOTES_vX.Y.Z.md files into docs/releases/.
• Updated release scripts, release preflight, tests and docs to use docs/releases/RELEASE_NOTES_vX.Y.Z.md.
• Improved workflow evidence packs with review/verify artifacts, offload IDs, harness contracts, diagram validation, eval reports and release evidence.
• Improved harness doctor so it reports active workflow, contract presence, failure count, latest verification status and suggested prevention action.
• Updated Workflow Rail, Harness Rail, Diagram Rail, spec workflow and release docs for v0.7.0.

Security

• Workflow verification and evidence remain local and do not publish packages, create GitHub releases or run destructive commands.
• Diagram Rail validates local Markdown/Mermaid files only.
• Harness contracts still validate by default without executing configured shell commands.

Notes

• Historical npm backfill for v0.5.0, v0.5.1, v0.5.2 and v0.6.0 should use the backfill dist-tag only when the historical checkout builds, tests and publishes safely.
• During v0.7.0 prep, v0.5.0 backfill was deferred because the historical checkout hit stale test failures and npm publish required a one-time password.
• SotuRail still does not expose arbitrary shell execution through MCP.