spec-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SpecOps Spec Metadata",
  "description": "Per-spec metadata file (spec.json) tracking lifecycle status, authorship, and review state",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^(?!\\.{1,2}$)[a-zA-Z0-9._-]+$",
      "description": "Spec identifier matching the directory name"
    },
    "type": {
      "type": "string",
      "enum": ["feature", "bugfix", "refactor"],
      "description": "Type of specification"
    },
    "status": {
      "type": "string",
      "enum": ["draft", "in-review", "approved", "self-approved", "implementing", "completed"],
      "description": "Current lifecycle status"
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "Spec version, incremented on each revision round"
    },
    "created": {
      "type": "string",
      "maxLength": 30,
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "ISO 8601 timestamp when the spec was first created"
    },
    "updated": {
      "type": "string",
      "maxLength": 30,
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "ISO 8601 timestamp when spec.json was last modified"
    },
    "author": {
      "type": "object",
      "description": "Engineer who created the spec (populated from git config)",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 100
        }
      },
      "required": ["name"],
      "additionalProperties": false
    },
    "reviewers": {
      "type": "array",
      "maxItems": 20,
      "description": "List of reviewers and their review status",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "status": {
            "type": "string",
            "enum": ["pending", "approved", "changes-requested"]
          },
          "reviewedAt": {
            "type": "string",
            "maxLength": 30,
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
            "description": "ISO 8601 timestamp of the review"
          },
          "round": {
            "type": "integer",
            "minimum": 1,
            "description": "Which review round this entry belongs to"
          },
          "selfApproval": {
            "type": "boolean",
            "description": "True when the reviewer is also the spec author (self-review)"
          }
        },
        "required": ["name", "status"],
        "additionalProperties": false
      }
    },
    "specopsCreatedWith": {
      "type": "string",
      "maxLength": 20,
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "SpecOps version that created this spec. Set once at creation, never updated."
    },
    "specopsUpdatedWith": {
      "type": "string",
      "maxLength": 20,
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "SpecOps version that last modified this spec. Updated on every spec.json write."
    },
    "reviewRounds": {
      "type": "integer",
      "minimum": 0,
      "description": "Current review iteration count"
    },
    "approvals": {
      "type": "integer",
      "minimum": 0,
      "description": "Count of current-round approvals"
    },
    "requiredApprovals": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of approvals needed. Set to 0 when review is disabled, otherwise copied from config at creation time."
    },
    "metrics": {
      "type": "object",
      "description": "Proxy productivity metrics captured at spec completion (Phase 4)",
      "properties": {
        "specArtifactTokensEstimate": {
          "type": "integer",
          "minimum": 0,
          "description": "Estimated tokens of spec artifacts (total chars / 4)"
        },
        "filesChanged": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of files changed during implementation"
        },
        "linesAdded": {
          "type": "integer",
          "minimum": 0,
          "description": "Lines added during implementation"
        },
        "linesRemoved": {
          "type": "integer",
          "minimum": 0,
          "description": "Lines removed during implementation"
        },
        "tasksCompleted": {
          "type": "integer",
          "minimum": 0,
          "description": "Count of tasks with Completed status"
        },
        "acceptanceCriteriaVerified": {
          "type": "integer",
          "minimum": 0,
          "description": "Count of checked acceptance criteria checkboxes"
        },
        "specDurationMinutes": {
          "type": "integer",
          "minimum": 0,
          "description": "Elapsed minutes from spec creation to completion"
        }
      },
      "additionalProperties": false
    },
    "evaluation": {
      "type": "object",
      "description": "Adversarial evaluation results from spec evaluation (Phase 2 exit gate) and implementation evaluation (Phase 4A)",
      "properties": {
        "spec": {
          "type": "object",
          "description": "Spec quality evaluation results",
          "properties": {
            "iterations": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of spec evaluation iterations completed"
            },
            "passed": {
              "type": "boolean",
              "description": "Whether the final spec evaluation passed all dimension thresholds"
            },
            "scores": {
              "type": "object",
              "description": "Final scores per dimension (dimension name to integer 1-10)",
              "patternProperties": {
                "^[a-zA-Z][a-zA-Z ]*$": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 10
                }
              },
              "additionalProperties": false
            },
            "evaluatedAt": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$"
            }
          },
          "additionalProperties": false
        },
        "implementation": {
          "type": "object",
          "description": "Implementation quality evaluation results",
          "properties": {
            "iterations": {
              "type": "integer",
              "minimum": 0,
              "description": "Number of implementation evaluation iterations completed"
            },
            "passed": {
              "type": "boolean",
              "description": "Whether the final implementation evaluation passed all dimension thresholds"
            },
            "scores": {
              "type": "object",
              "description": "Final scores per dimension (dimension name to integer 1-10)",
              "patternProperties": {
                "^[a-zA-Z][a-zA-Z ]*$": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 10
                }
              },
              "additionalProperties": false
            },
            "evaluatedAt": {
              "type": "string",
              "maxLength": 30,
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$"
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "partOf": {
      "type": "string",
      "maxLength": 100,
      "pattern": "^(?!\\.{1,2}$)[a-zA-Z0-9._-]+$",
      "description": "Initiative ID this spec belongs to"
    },
    "relatedSpecs": {
      "type": "array",
      "maxItems": 20,
      "uniqueItems": true,
      "description": "Informational cross-references to related specs",
      "items": {
        "type": "string",
        "maxLength": 100,
        "pattern": "^(?!\\.{1,2}$)[a-zA-Z0-9._-]+$"
      }
    },
    "productionLearnings": {
      "type": "array",
      "maxItems": 50,
      "description": "Production learnings discovered post-deployment linked to this spec",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^L-[a-zA-Z0-9._-]+-[0-9]+$",
            "description": "Learning ID (references learnings.json)"
          },
          "category": {
            "type": "string",
            "enum": ["performance", "scaling", "security", "reliability", "ux", "design", "other"],
            "description": "Category of learning"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low"],
            "description": "Severity level"
          },
          "status": {
            "type": "string",
            "enum": ["discovered", "investigating", "resolved", "deferred"],
            "description": "Current resolution status"
          }
        },
        "required": ["id", "category"],
        "additionalProperties": false
      }
    },
    "specDependencies": {
      "type": "array",
      "maxItems": 50,
      "description": "Explicit dependencies on other specs with enforcement",
      "items": {
        "type": "object",
        "properties": {
          "specId": {
            "type": "string",
            "maxLength": 100,
            "pattern": "^(?!\\.{1,2}$)[a-zA-Z0-9._-]+$",
            "description": "ID of the dependency spec"
          },
          "reason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Why this spec depends on the other"
          },
          "required": {
            "type": "boolean",
            "description": "If true, Phase 3 is blocked until the dependency is completed"
          },
          "contractRef": {
            "type": "string",
            "maxLength": 200,
            "pattern": "^(?!/)(?!.*\\.\\.)(?!.*//)[a-zA-Z0-9._/-]+$",
            "description": "Relative path to an interface contract or shared artifact (no absolute paths or .. segments)"
          }
        },
        "required": ["specId", "reason"],
        "additionalProperties": false
      }
    }
  },
  "required": ["id", "type", "status", "version", "created", "updated", "author"],
  "additionalProperties": false
}