feat(protocol): v1.1 — record metadata extension + version field relaxation - #1
Open
cagodoy wants to merge 2 commits into
Open
feat(protocol): v1.1 — record metadata extension + version field relaxation#1cagodoy wants to merge 2 commits into
cagodoy wants to merge 2 commits into
Conversation
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)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The protocol defines 6 record types. Of those, 4 already carry an optional
metadatafield (ActorRecord,AgentRecord,ExecutionRecord,FeedbackRecord). The remaining 2 —TaskRecordandCycleRecord— 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) ornotes(free-form text).This PR adds
metadatato both records and bumps the protocol to v1.1.Changes
1. Record metadata extension (6/6 symmetry)
task_record_schema.yamlmetadataobject(additionalProperties: true)cycle_record_schema.yamlmetadataobject(additionalProperties: true)Both include inline examples:
{ "epic": true, "phase": "implementation" }), external tool refs ({ "jira": "AUTH-42" }){ "epic": true, "files": {...} }), sprint tracking ({ "sprint": 24, "velocity": 42 })RFC updates:
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.versionfield inembedded_metadata_schema.yamlchanged from:This accepts any
MAJOR.MINORstring ("1.0","1.1","2.0", etc.) without requiring a schema update on every protocol release. Follows the HTTP/TLS convention — strictDIGIT.DIGITformat, no semver, no pre-release suffixes.RFC-01 §4.1 field table updated to reflect the new pattern constraint.
Protocol impact
Derivability
RFC field descriptions are derivable from the YAML schemas. The
exampleskey in each schema maps to the JSON examples in each RFC section. Field semantics in the RFC expand on the schemadescriptionwithout contradiction.