Skip to content

UCF-RS 0.3.0 Release Notes

Release Date: October 2026
Git Tag: v0.3.0
Package: ucf-rs@0.3.0

UCF-RS 0.3.0 is a major hardening and release-readiness milestone that adds distribution via npm, strict store validation, consistent exit codes, comprehensive documentation with Zensical, and an expanded test suite.

What's New in 0.3.0

1. E_STORE_UNINITIALIZED in Strict Status Checks

  • status --strict now detects uninitialized stores (.ucf-rs/ missing or empty) and emits diagnostic E_STORE_UNINITIALIZED, exiting with code 1 (EXIT_CHECK_FAILURE).
  • Normal status continues to report store presence cleanly without crashing.

2. Standardized Exit Code Contract

  • Established a unified, deterministic exit code contract across all commands:
  • 0 (EXIT_OK): Command succeeded.
  • 1 (EXIT_CHECK_FAILURE): Operational check failure (status --strict on diagnostics/unaccepted evidence/uninitialized store, reconcile --partition-id when not reconciled, session open with diagnostics).
  • 2 (EXIT_VALIDATION_ERROR): CLI argument errors, precondition failures, or E_RECOVERY_RETRY_REQUIRED when a mutating command recovers a pending transaction.

3. Corrected --task-context Documentation

  • Clarified the semantics of --task-context in README, User Guide, and Agent Guide: the flag permits ad-hoc task handles for the current invocation without requiring an entry in docs/handle-registry.jsonl or writing to .ucf-rs/handle-cache.jsonl.
  • Documented persistent handle caching via import-registry as the permanent alternative.

4. Doc-to-Code Audit Recipe

  • Added docs/doc-audit-recipe.md detailing how to audit documentation claims against real codebases using only existing UCF-RS features and an external sidecar JSONL file, with zero modifications to the audited repository.
  • Reconciled ephemeral input staging inside .ucf-rs/ with the "never hand-edit .ucf-rs/" invariant and explained why paths are strictly confined to --root.

5. Fork Proposal for Claim Audits

  • Added docs/fork-proposal-doc-audit.md, a formal specification for a domain-specific doc-audit fork (ucf-doc-audit) that persists claims, documentation line anchors, and first-class supported / divergent / unsupported dispositions under its own schema namespace (ucf-doc-audit.*).

6. npm Distribution (ucf-rs)

  • Added npm package packaging with bin/ucf-rs.js, providing an automated launcher that discovers local Python 3.10+ environments with shell-injection safety and transparent exit code passthrough.
  • Supports global installation (npm install -g ucf-rs) and instant execution via npx ucf-rs.

7. Zensical Documentation Site

  • Built a static documentation site powered by Zensical with strict validation enabled (site_url: https://paragon-ux.github.io/UCF-RS/).
  • Added docs/glossary.md with plain-language definitions for core concepts (overlay, handle, partition, ledger, epoch, JSONL, OIDC).

8. Expanded Test & Release Verification Battery

  • Expanded test suite from 61 to 75+ unit tests, covering version consistency, npm package metadata, Node.js wrapper invocation, shell-injection safety, and uninitialized store exit codes.
  • Added release verification tools:
  • scripts/check_versions.py: Enforces version agreement across all manifests.
  • scripts/check_package.py: Dry-run tarball check preventing leakage of untracked, machine, or personal path strings.
  • scripts/smoke_npm_install.py: End-to-end tarball packing and installation smoke test.

Upgrade Path

Upgrading from 0.2.0 or 0.1.0 requires no changes to existing .ucf-rs/ store files. All canonical hash boundaries and JSON schemas remain 100% backward-compatible.