feat(spec): v0.3 four-property schema with gsd-plugin alignment

[qmarcelle]

Summary

• Rewrites schema/v1.json to the v0.3 four-property shape: manual, generated, agents, health
• generated.specVersion const-locked to "0.3", with fileIndex and frameworkManifest as canonical gsd-plugin v2.42.3 read paths
• manual.fragileFiles and manual.coChangePatterns are the two manual-side gsd-plugin read paths
• Canonical write path corrected to .agents/agents.workspace.json (v0.2.0 incorrectly stated repo root)
• Adds three examples: minimal-v0.3.json, populated-v0.3.json, with-manual-block-v0.3.json
• Updates CHANGELOG with [0.3.0] breaking-change section

Breaking changes

• Schema shape changed — v0.2 documents will fail validation against this schema
• generated.files → generated.fileIndex; top-level version → generated.specVersion
• Canonical path corrected from repo root to .agents/agents.workspace.json

Test plan

• pnpm --filter @workspacejson/spec exec vitest run passes
• validate() export accepts all three new example files
• validateLegacy() gracefully rejects v0.3 documents (returns false, no throw)
• Downstream: Stream-W-impl updates src/index.ts exports and bumps to 0.3.0

[Copilot]

Pull request overview

Updates the @workspacejson/spec JSON Schema to the proposed v0.3 “four-property” document shape (manual, generated, agents, health) and adds example v0.3 documents, with corresponding release notes and a small package-metadata test adjustment.

Changes:

• Rewrites schema/v1.json to the v0.3 structure with generated.specVersion const-locked to "0.3".
• Adds three v0.3 example JSON documents under packages/spec/examples/.
• Adds a 0.3.0 changelog entry and updates package metadata assertions in tests.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/spec/schema/v1.json	Replaces the previous schema with a new v0.3 four-block schema layout and updated field locations.
packages/spec/examples/minimal-v0.3.json	Adds a minimal v0.3 example document.
packages/spec/examples/populated-v0.3.json	Adds a more complete v0.3 example document showing framework/fileIndex usage.
packages/spec/examples/with-manual-block-v0.3.json	Adds an example demonstrating the manual block (fragile files and co-change patterns).
packages/spec/CHANGELOG.md	Documents a 0.3.0 breaking-change release and migration notes.
packages/agents-audit/src/package-metadata.test.ts	Adjusts package metadata expectations (repository directory and package versions).

Comments suppressed due to low confidence (4)

packages/spec/schema/v1.json:22

• manual.fragileFiles[] entries don’t require a path (and allow arbitrary keys), so {} is currently valid even though it’s not meaningful. Consider adding required: ["path"] (and likely additionalProperties: false) on the item schema to enforce minimally useful entries and generate stronger TypeScript types.

          "items": {
            "type": "object",
            "properties": {
              "path": { "type": "string" },
              "reason": { "type": "string" }
            }
          }

packages/spec/schema/v1.json:56

• generated.frameworkManifest[] items define name/version/confidence but don’t mark any of them as required, so objects like {} validate. If these are intended to be real detections, consider requiring at least name and confidence (and possibly additionalProperties: false) to keep validation and generated types aligned with the documented shape.

          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "version": { "type": "string" },
              "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
            }
          }

packages/spec/CHANGELOG.md:25

• The migration guidance says “Fall back to v0.1 shape if specVersion is absent”, but the immediately preceding releases in this repo are 0.2.x and also used a different top-level versioning approach. Consider updating this guidance to reference the actual legacy shape(s) (e.g., v0.2) so consumers migrate correctly.

### Migration
Check `generated.specVersion === "0.3"` to detect v0.3 documents. Fall back to v0.1 shape if `specVersion` is absent.

packages/spec/CHANGELOG.md:21

• The changelog says the package now includes an examples/ directory, but packages/spec/package.json’s files whitelist currently excludes examples, so these JSON files won’t be published to npm. Either add examples to the published files list or adjust the release notes to match what will actually ship.

### Added
- `examples/` directory with minimal, populated, and with-manual-block example files.
- `validate()` and `validateLegacy()` exports in `src/index.ts`.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.