Changelog

v0.4.1 - 2026-06-02

Filename rename + v0.4 schema fields.

Filename rename

The canonical file is now workspace.json at .agents/workspace.json. The previous name agents.workspace.json was redundant once .agents/ provided the namespace. Old paths remain supported as read fallbacks with deprecation warnings.

Migration: rename your file if you have it at the old path:

mkdir -p .agents
mv .agents/agents.workspace.json .agents/workspace.json
# or if at repo root:
mkdir -p .agents
mv agents.workspace.json .agents/workspace.json

v0.4 schema changes

• specVersion is now "0.4". v0.3 documents ("specVersion": "0.3") are rejected by v0.4 consumers.
• generated.fileIndex (map) replaced by generated.fragility[] (array). Each entry has file, changeCount, revertCount, revertRate, fragilityScore, and excluded.
• generated.coChangeClusters[] replaced by generated.coChange[]. Each entry has files, rate, occurrences, and generated (boolean — use true to skip tooling-coupled pairs like lockfiles).
• health.workflowFragility, health.codebaseHealth, health.changeVolatility — three aggregate health scores (0–1) promoted from escape hatch to typed fields.
• agents-audit generate now writes to .agents/workspace.json. The audit reader checks .agents/workspace.json → .agents/agents.workspace.json → workspace.json at root.
• All three packages ship at 0.4.1: @workspacejson/spec, @workspacejson/rules, agents-audit.

v0.3.0 - 2026-05-12

Breaking changes — v0.3 changes the top-level shape. All four sections are now required.

• Schema shape changed to four-property structure: manual, generated, agents, health
• Canonical write path: .agents/agents.workspace.json
• Top-level version field removed; schema version now lives at generated.specVersion = "0.3"
• Per-file fragility data at generated.fileIndex.{path} (not files.{path})
• Framework detection at generated.frameworkManifest
• health.intelligenceState enum: INSUFFICIENT_DATA | OBSERVING | CONFIDENT
• Field names match jnuyens/gsd-plugin v2.42.3 SessionStart read paths (first shipped consumer)
• validate() and validateLegacy() exported from @workspacejson/spec
• JSON Schema published at https://www.workspacejson.dev/schema/v1.json

Migration: check generated.specVersion === "0.3" to detect v0.3 documents. Fall back to v0.1 shape if specVersion is absent.

v0.1.0 - 2026-05-05

Initial public release.

• Core spec stable: file index, framework manifest, agent file references, stable health signals
• Experimental fields: structuralPhase, llmContextStaleness, packageDensity, testCoverageRatio, bootstrapOverride
• Reference CLI agents-audit published to npm
• JSON Schema published as @workspacejson/spec
• Rule library published as @workspacejson/rules
• Five v0.1.1 audit rules: missing-file-reference, pattern-zero-match, framework-drift, section-staleness, convention-mismatch
• Apache 2.0 across all artifacts