gitgovernance · cagodoy · Feb 24, 2026 · Feb 24, 2026
diff --git 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` &#124; `agent` &#124; `task` &#124; `execution` &#124; `feedback` &#124; `cycle` &#124; `workflow` &#124; `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
@@ -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
@@ -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
@@ -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`
 
@@ -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
@@ -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`
 
@@ -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/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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)
 
@@ -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/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
@@ -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
@@ -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
@@ -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)
 
@@ -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"

diff --git 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)