From bc45c01612a7ffc7d9afeb8ec531a73a86267f10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilo=20Acu=C3=B1a?= Date: Wed, 25 Feb 2026 03:14:18 +0700 Subject: [PATCH 1/2] feat(protocol): add metadata field to TaskRecord and CycleRecord schemas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- 04_task.md | 59 +++++++++++++++++++++++++++++ 05_cycle.md | 64 ++++++++++++++++++++++++++++++++ schemas/cycle_record_schema.yaml | 12 ++++++ schemas/task_record_schema.yaml | 12 ++++++ 4 files changed, 147 insertions(+) diff --git a/04_task.md b/04_task.md index e73b41a..36954c3 100644 --- a/04_task.md +++ b/04_task.md @@ -111,6 +111,26 @@ The Task Record is the `payload` inside an Embedded Metadata envelope (RFC-01) w | `tags` | array of strings | items: `^[a-z0-9-]+(:[a-z0-9-]+)*$`, minLength: 1 | `[]` | `key:value` tags for categorization (e.g. `skill:react`, `category:bug`). | | `references` | array of strings | items: minLength: 1, maxLength: 500 | `[]` | Typed links to related resources (§7). | | `notes` | string | minLength: 1 | — | Additional context, decisions, or clarifications. | +| `metadata` | object | additionalProperties: true | — | Structured data for programmatic consumption (see §4.3). | + +### 4.3. Metadata + +| Property | Value | +|----------|-------| +| **Field** | `metadata` | +| **Type** | `object` | +| **Required** | No | +| **additionalProperties** | `true` | + +An optional field for structured, machine-readable data. While `tags` provide flat classification and `notes` provide free-form human text, `metadata` carries structured data intended for programmatic consumption by products, workflows, or external tools. + +**Semantics:** The protocol does not prescribe any keys or structure within `metadata`. Its contents are domain-specific and opaque to the protocol layer. Implementations SHOULD preserve metadata faithfully across read/write cycles. + +**Common use cases:** +- **Epic modeling:** `{ "epic": true, "phase": "active", "files": {...} }` +- **External tool integration:** `{ "jira": "PROJ-123", "linearId": "LIN-456" }` +- **Agent metrics:** `{ "estimatedHours": 4, "model": "claude-opus-4-6" }` +- **Compliance tagging:** `{ "regulation": "SOC2", "controlId": "CC6.1" }` No additional properties are allowed at the root level. @@ -409,6 +429,45 @@ A task with full lifecycle — created, audited, executed, and approved. } ``` +### 11.4. Task with Metadata (epic modeling) + +A task that uses metadata to associate structured, machine-readable data. + +```json +{ + "header": { + "version": "1.0", + "type": "task", + "payloadChecksum": "m4n5o6a1b2c3789012345678901234567890123456789012345678901234pqrs", + "signatures": [ + { + "keyId": "agent:planner", + "role": "author", + "notes": "Task created as part of OAuth epic with structured metadata for tracking", + "signature": "VwXyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNoPqRsTuA==", + "timestamp": 1752550000 + } + ] + }, + "payload": { + "id": "1752550000-task-implement-oauth2-flow", + "title": "Implement OAuth2 authorization code flow", + "status": "active", + "priority": "high", + "description": "Implement OAuth2 authorization code flow with PKCE for the web application. Must support GitHub and Google providers.", + "cycleIds": ["1752270000-cycle-auth-mvp"], + "tags": ["skill:security", "category:feature"], + "references": ["file:docs/architecture/auth-flow.md"], + "metadata": { + "epic": true, + "phase": "implementation", + "estimatedHours": 8, + "jira": "AUTH-42" + } + } +} +``` + --- ## 12. Security Considerations diff --git a/05_cycle.md b/05_cycle.md index 8626e84..6607368 100644 --- a/05_cycle.md +++ b/05_cycle.md @@ -115,6 +115,26 @@ The Cycle Record is the `payload` inside an Embedded Metadata envelope (RFC-01) | `childCycleIds` | array of strings | items: `^\d{10}-cycle-[a-z0-9-]{1,50}$`, maxLength: 67 | `[]` | IDs of child cycles for hierarchical composition (§6.2). | | `tags` | array of strings | items: `^[a-z0-9-]+(:[a-z0-9-]+)*$`, maxLength per item: 100 | `[]` | `key:value` tags for categorization (e.g. `sprint:24`, `team:backend`). | | `notes` | string | minLength: 1 | — | Description of the cycle's goals, objectives, and context. | +| `metadata` | object | additionalProperties: true | — | Structured data for programmatic consumption (see §4.3). | + +### 4.3. Metadata + +| Property | Value | +|----------|-------| +| **Field** | `metadata` | +| **Type** | `object` | +| **Required** | No | +| **additionalProperties** | `true` | + +An optional field for structured, machine-readable data. While `tags` provide flat classification and `notes` provide free-form human text, `metadata` carries structured data intended for programmatic consumption by products, workflows, or external tools. + +**Semantics:** The protocol does not prescribe any keys or structure within `metadata`. Its contents are domain-specific and opaque to the protocol layer. Implementations SHOULD preserve metadata faithfully across read/write cycles. + +**Common use cases:** +- **Epic lifecycle:** `{ "epic": true, "phase": "active", "files": { "overview": "...", "roadmap": "...", "implementation_plan": "..." } }` +- **Sprint tracking:** `{ "sprint": 24, "velocity": 42, "team": "backend" }` +- **OKR alignment:** `{ "okr": "growth-q4", "keyResult": "KR-3" }` +- **Budget allocation:** `{ "budget": 50000, "currency": "USD" }` No additional properties are allowed at the root level. @@ -325,6 +345,50 @@ A high-level cycle that composes child cycles instead of directly referencing ta } ``` +### 10.4. Epic Cycle with Metadata + +A cycle representing an epic, using metadata to store structured lifecycle information. + +```json +{ + "header": { + "version": "1.0", + "type": "cycle", + "payloadChecksum": "k9l0m1a1b2c3789012345678901234567890123456789012345678901234nopq", + "signatures": [ + { + "keyId": "human:tech-lead", + "role": "author", + "notes": "Auth epic created with structured metadata for lifecycle tracking", + "signature": "TuVwXyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNoPqRsTuVwXyZaBcDeFgHiJkLmNoPqRsA==", + "timestamp": 1754700000 + } + ] + }, + "payload": { + "id": "1754700000-cycle-q4-auth-epic", + "title": "Q4 2025 - Auth Epic", + "status": "active", + "taskIds": [ + "1752550000-task-implement-oauth2-flow", + "1752360900-task-2fa-implementation" + ], + "tags": ["epic", "auth"], + "metadata": { + "epic": true, + "phase": "active", + "files": { + "overview": "epics/auth/overview.md", + "roadmap": "epics/auth/roadmap.md", + "implementation_plan": "epics/auth/implementation_plan.md" + }, + "velocity": 42, + "team": "backend" + } + } +} +``` + --- ## 11. Security Considerations diff --git a/schemas/cycle_record_schema.yaml b/schemas/cycle_record_schema.yaml index 64d50dd..ea65828 100644 --- a/schemas/cycle_record_schema.yaml +++ b/schemas/cycle_record_schema.yaml @@ -94,6 +94,18 @@ properties: minLength: 1 description: "Optional description of the cycle's goals, objectives, and context." + metadata: + type: object + additionalProperties: true + description: | + Optional structured data for machine consumption. + Use this field for domain-specific data that needs to be programmatically processed. + Extends the strategic grouping with structured, queryable attributes. + Common use cases: epic lifecycle, sprint configuration, OKR tracking, budget allocation. + examples: + - { "epic": true, "phase": "active", "files": { "overview": "overview.md", "roadmap": "roadmap.md", "plan": "implementation_plan.md" } } + - { "sprint": 24, "velocity": 42, "team": "backend" } + examples: # Example 1: Sprint (2-week iteration) - id: "1754400000-cycle-sprint-24-api-performance" diff --git a/schemas/task_record_schema.yaml b/schemas/task_record_schema.yaml index c0dc49b..f3712a5 100644 --- a/schemas/task_record_schema.yaml +++ b/schemas/task_record_schema.yaml @@ -106,6 +106,18 @@ properties: minLength: 1 description: "Additional comments, decisions made or added context" + metadata: + type: object + additionalProperties: true + description: | + Optional structured data for machine consumption. + Use this field for domain-specific data that needs to be programmatically processed. + Complements tags (classification) and notes (free text) with structured, queryable data. + Common use cases: epic metadata, external tool references, agent metrics, compliance tags. + examples: + - { "epic": true, "phase": "implementation", "files": { "overview": "overview.md" } } + - { "jira": "AUTH-42", "storyPoints": 5 } + examples: # Example 1: New task in draft state - id: "1752274500-task-implement-oauth-flow" From 6dbceef042136f9d83be91a91d5bfcbd3f1f33b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Camilo=20Acu=C3=B1a?= Date: Wed, 25 Feb 2026 03:40:04 +0700 Subject: [PATCH 2/2] feat(protocol): bump version to 1.1, relax version field to pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- 01_embedded.md | 4 ++-- 02_actor.md | 2 +- 03_agent.md | 2 +- 04_task.md | 2 +- 05_cycle.md | 2 +- 06_execution.md | 2 +- 07_feedback.md | 2 +- 08_workflow.md | 2 +- README.md | 10 +++++----- schemas/actor_record_schema.yaml | 2 +- schemas/agent_record_schema.yaml | 2 +- schemas/cycle_record_schema.yaml | 2 +- schemas/embedded_metadata_schema.yaml | 6 +++--- schemas/execution_record_schema.yaml | 2 +- schemas/feedback_record_schema.yaml | 2 +- schemas/task_record_schema.yaml | 2 +- schemas/workflow_record_schema.yaml | 2 +- 17 files changed, 24 insertions(+), 24 deletions(-) diff --git a/01_embedded.md b/01_embedded.md index 61d23af..ab74584 100644 --- a/01_embedded.md +++ b/01_embedded.md @@ -19,7 +19,7 @@ # RFC-01: Embedded Metadata -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-04\ > Schema: `schemas/embedded_metadata_schema.yaml` @@ -78,7 +78,7 @@ No additional properties are allowed at the root level. | Field | Type | Constraint | Description | |:------|:-----|:-----------|:------------| -| `version` | string | `"1.0"` | Protocol version. | +| `version` | string | `^\d+\.\d+$` | Protocol version in MAJOR.MINOR format (e.g. `"1.1"`, `"2.0"`). | | `type` | enum | `actor` | `agent` | `task` | `execution` | `feedback` | `cycle` | `workflow` | `custom` | Determines which schema validates the payload. | | `payloadChecksum` | string | `^[a-fA-F0-9]{64}$` | SHA-256 hash of the canonicalized payload (see §5.1). | | `signatures` | array | `minItems: 1` | One or more Signature objects (see §4.3). | diff --git a/02_actor.md b/02_actor.md index 58268e3..e5da99d 100644 --- a/02_actor.md +++ b/02_actor.md @@ -19,7 +19,7 @@ # RFC-02: Actor Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-04\ > Schema: `schemas/actor_record_schema.yaml` diff --git a/03_agent.md b/03_agent.md index 041119d..d4bb8a2 100644 --- a/03_agent.md +++ b/03_agent.md @@ -19,7 +19,7 @@ # RFC-03: Agent Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-20\ > Schema: `schemas/agent_record_schema.yaml` diff --git a/04_task.md b/04_task.md index 36954c3..707bb94 100644 --- a/04_task.md +++ b/04_task.md @@ -19,7 +19,7 @@ # RFC-04: Task Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-04\ > Schema: `schemas/task_record_schema.yaml` diff --git a/05_cycle.md b/05_cycle.md index 6607368..cc85345 100644 --- a/05_cycle.md +++ b/05_cycle.md @@ -19,7 +19,7 @@ # RFC-05: Cycle Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-20\ > Schema: `schemas/cycle_record_schema.yaml` diff --git a/06_execution.md b/06_execution.md index a4a70f6..18803a8 100644 --- a/06_execution.md +++ b/06_execution.md @@ -19,7 +19,7 @@ # RFC-06: Execution Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-04\ > Schema: `schemas/execution_record_schema.yaml` diff --git a/07_feedback.md b/07_feedback.md index de2dcd8..8d1f7c0 100644 --- a/07_feedback.md +++ b/07_feedback.md @@ -19,7 +19,7 @@ # RFC-07: Feedback Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-17\ > Schema: `schemas/feedback_record_schema.yaml` diff --git a/08_workflow.md b/08_workflow.md index 897be71..350803a 100644 --- a/08_workflow.md +++ b/08_workflow.md @@ -19,7 +19,7 @@ # RFC-08: Workflow Record -> Version: 1.0 | Status: Stable\ +> Version: 1.1 | Status: Stable\ > Created: May 2025 | Last updated: 2026-02-17\ > Schema: `schemas/workflow_record_schema.yaml` diff --git a/README.md b/README.md index 5e798c4..246cdee 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,13 @@ SPDX-License-Identifier: Apache-2.0 --> -# GitGovernance Protocol (v1.0) +# GitGovernance Protocol (v1.1) > **Cryptographic governance for humans and AI agents. Open protocol. Offline-verifiable. Git-native.** -The complete, implementation-agnostic specification for the GitGovernance Protocol v1.0 — 8 RFCs and 8 JSON Schemas defining how decisions, actions, and exceptions are recorded as signed, immutable artifacts in Git. +The complete, implementation-agnostic specification for the GitGovernance Protocol v1.1 — 8 RFCs and 8 JSON Schemas defining how decisions, actions, and exceptions are recorded as signed, immutable artifacts in Git. -**Status**: v1.0 Stable\ +**Status**: v1.1 Stable\ **Created**: May 2025\ **License**: Apache-2.0 @@ -21,7 +21,7 @@ Every record in the protocol follows the same pattern: domain data (payload) wra ``` ┌─ Header ────────────────────────────────────────────────┐ -│ version: "1.0" │ +│ version: "1.1" │ │ type: "execution" │ │ payloadChecksum: SHA-256(canonicalize(payload)) │ │ signatures: │ @@ -148,7 +148,7 @@ The protocol uses **MAJOR.MINOR** versioning: - **v1.x** (minor) — New RFCs, new optional fields in existing schemas, new examples, clarifications. Backwards-compatible: any implementation that validates v1.0 records will continue to work with v1.x records. - **v2.0** (major) — Breaking changes to existing RFCs or required schema fields. Requires a migration path. -**Stability guarantee**: v1.0 schemas are frozen. Required fields, field types, and validation patterns will not change within the v1.x line. New optional fields may be added. +**Stability guarantee**: v1.x schemas maintain backward compatibility. Required fields, field types, and validation patterns will not change within the v1.x line. New optional fields may be added. **Amendment process**: Changes are proposed via GitHub Issues, discussed openly, and published as GitHub Releases with a changelog describing what changed and why. diff --git a/schemas/actor_record_schema.yaml b/schemas/actor_record_schema.yaml index d695f57..0a4f347 100644 --- a/schemas/actor_record_schema.yaml +++ b/schemas/actor_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# ActorRecord Schema (v1.0) +# ActorRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-02 (02_actor.md) diff --git a/schemas/agent_record_schema.yaml b/schemas/agent_record_schema.yaml index af2f841..1a64eb9 100644 --- a/schemas/agent_record_schema.yaml +++ b/schemas/agent_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# AgentRecord Schema (v1.0) +# AgentRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-03 (03_agent.md) diff --git a/schemas/cycle_record_schema.yaml b/schemas/cycle_record_schema.yaml index ea65828..575d9bb 100644 --- a/schemas/cycle_record_schema.yaml +++ b/schemas/cycle_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# CycleRecord Schema (v1.0) +# CycleRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-05 (05_cycle.md) diff --git a/schemas/embedded_metadata_schema.yaml b/schemas/embedded_metadata_schema.yaml index 2a699ec..a0555d9 100644 --- a/schemas/embedded_metadata_schema.yaml +++ b/schemas/embedded_metadata_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# EmbeddedMetadata Schema (v1.0) +# EmbeddedMetadata Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-01 (01_embedded.md) @@ -29,8 +29,8 @@ properties: properties: version: type: string - enum: ["1.0"] - description: "Version of the embedded metadata format." + pattern: "^\\d+\\.\\d+$" + description: "Protocol version in MAJOR.MINOR format (e.g. \"1.1\", \"2.0\")." type: type: string enum: diff --git a/schemas/execution_record_schema.yaml b/schemas/execution_record_schema.yaml index 2f56b7f..eb29798 100644 --- a/schemas/execution_record_schema.yaml +++ b/schemas/execution_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# ExecutionRecord Schema (v1.0) +# ExecutionRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-06 (06_execution.md) diff --git a/schemas/feedback_record_schema.yaml b/schemas/feedback_record_schema.yaml index cd5d2df..c00200a 100644 --- a/schemas/feedback_record_schema.yaml +++ b/schemas/feedback_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# FeedbackRecord Schema (v1.0) +# FeedbackRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-07 (07_feedback.md) diff --git a/schemas/task_record_schema.yaml b/schemas/task_record_schema.yaml index f3712a5..b082990 100644 --- a/schemas/task_record_schema.yaml +++ b/schemas/task_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# TaskRecord Schema (v1.0) +# TaskRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-04 (04_task.md) diff --git a/schemas/workflow_record_schema.yaml b/schemas/workflow_record_schema.yaml index da092c1..f066e69 100644 --- a/schemas/workflow_record_schema.yaml +++ b/schemas/workflow_record_schema.yaml @@ -14,7 +14,7 @@ # limitations under the License. # # --- -# WorkflowRecord Schema (v1.0) +# WorkflowRecord Schema (v1.1) # Part of the GitGovernance Protocol — designed and maintained by GitGovernance. # Specification: RFC-08 (08_workflow.md)