Skip to content

feat(protocol): v1.1 — record metadata extension + version field relaxation - #1

Open
cagodoy wants to merge 2 commits into
mainfrom
feat/record-metadata-extension
Open

feat(protocol): v1.1 — record metadata extension + version field relaxation#1
cagodoy wants to merge 2 commits into
mainfrom
feat/record-metadata-extension

Conversation

@cagodoy

@cagodoy cagodoy commented Feb 24, 2026

Copy link
Copy Markdown
Member

Summary

The protocol defines 6 record types. Of those, 4 already carry an optional metadata field (ActorRecord, AgentRecord, ExecutionRecord, FeedbackRecord). The remaining 2 — TaskRecord and CycleRecord — do not.

This asymmetry prevents products, workflows, and external tools from associating structured, machine-readable data with tasks or cycles without abusing tags (flat classification) or notes (free-form text).

This PR adds metadata to both records and bumps the protocol to v1.1.

Changes

1. Record metadata extension (6/6 symmetry)

Schema Field added Type Required
task_record_schema.yaml metadata object (additionalProperties: true) No
cycle_record_schema.yaml metadata object (additionalProperties: true) No

Both include inline examples:

  • Task: epic modeling ({ "epic": true, "phase": "implementation" }), external tool refs ({ "jira": "AUTH-42" })
  • Cycle: epic lifecycle ({ "epic": true, "files": {...} }), sprint tracking ({ "sprint": 24, "velocity": 42 })

RFC updates:

  • RFC-04 (Task) §4.9 Metadata — field table, semantics, use cases, JSON example
  • RFC-05 (Cycle) §4.7 Metadata — field table, semantics, use cases, JSON example

Both sections follow the documentation pattern established in RFC-06 §4.7 (ExecutionRecord metadata) and RFC-07 §4.8 (FeedbackRecord metadata).

2. Version bump to v1.1

All 8 RFC headers, 8 schema headers, and README updated from v1.0 to v1.1.

JSON examples retain "version": "1.0" — they represent existing records created under v1.0, which remain valid.

3. Version field relaxation

The header.version field in embedded_metadata_schema.yaml changed from:

# Before
enum: ["1.0"]

# After
pattern: "^\d+\.\d+$"

This accepts any MAJOR.MINOR string ("1.0", "1.1", "2.0", etc.) without requiring a schema update on every protocol release. Follows the HTTP/TLS convention — strict DIGIT.DIGIT format, no semver, no pre-release suffixes.

RFC-01 §4.1 field table updated to reflect the new pattern constraint.

Protocol impact

  • Additive, non-breaking. The metadata field is optional — existing records without it remain valid.
  • Version bump: v1.0 → v1.1 (minor).
  • No migration required. Records created under v1.0 need no modification.
  • Validation: Schema-driven (AJV). No custom validation logic needed.

Derivability

RFC field descriptions are derivable from the YAML schemas. The examples key in each schema maps to the JSON examples in each RFC section. Field semantics in the RFC expand on the schema description without contradiction.

Extends TaskRecord (RFC-04) and CycleRecord (RFC-05) with an optional
metadata field — type object, additionalProperties true, not required.

This completes the 6/6 metadata symmetry across all record types.
ActorRecord, AgentRecord, ExecutionRecord and FeedbackRecord already
supported metadata; Task and Cycle did not.

Schema changes:
- task_record_schema.yaml: metadata field with examples
- cycle_record_schema.yaml: metadata field with examples

RFC updates:
- RFC-04 §4.9 Metadata: field semantics, use cases, examples
- RFC-05 §4.7 Metadata: field semantics, use cases, examples

Additive change — no required fields modified, no breaking changes.
Minor version bump (v1.0 → v1.1).
- Bump all RFC headers, schema headers, and README to v1.1
- Replace version enum ["1.0"] with pattern ^\d+\.\d+$ in
  embedded_metadata_schema.yaml — accepts any MAJOR.MINOR string
- Update RFC-01 field table to reflect pattern constraint
- JSON examples retain "version": "1.0" (existing records, still valid)
@cagodoy cagodoy changed the title feat(protocol): add metadata to TaskRecord and CycleRecord feat(protocol): v1.1 — record metadata extension + version field relaxation Feb 24, 2026
@cagodoy cagodoy closed this May 6, 2026
@cagodoy cagodoy reopened this May 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant