@dogfood-lab/schemas 1.2.0

package/src/json/dogfood-finding.schema.json

@@ -0,0 +1,414 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dogfood-lab/testing-os/packages/schemas/src/json/dogfood-finding.schema.json",
+  "title": "Dogfood Finding",
+  "description": "A reviewed, evidence-backed lesson extracted from one or more dogfood runs. The fourth contract alongside record, scenario, and policy. Findings are the smallest durable unit of reusable learning in dogfood-labs.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "finding_id",
+    "title",
+    "status",
+    "repo",
+    "product_surface",
+    "journey_stage",
+    "issue_kind",
+    "root_cause_kind",
+    "remediation_kind",
+    "transfer_scope",
+    "summary",
+    "source_record_ids",
+    "evidence"
+  ],
+  "additionalProperties": false,
+  "properties": {
+
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semver of the finding schema."
+    },
+
+    "finding_id": {
+      "type": "string",
+      "pattern": "^dfind-[a-z0-9][a-z0-9-]*$",
+      "minLength": 7,
+      "description": "Unique, stable, human-readable slug. Format: dfind-<repo-short>-<lesson-slug>."
+    },
+
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200,
+      "description": "Short descriptive sentence of the lesson."
+    },
+
+    "status": {
+      "type": "string",
+      "enum": ["candidate", "reviewed", "accepted", "rejected"],
+      "description": "Lifecycle status. Phase 1 does not enforce transition logic — only validates allowed values."
+    },
+
+    "repo": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$",
+      "description": "Full org/repo where the finding originated."
+    },
+
+    "product_surface": {
+      "type": "string",
+      "enum": ["cli", "desktop", "web", "api", "mcp-server", "npm-package", "plugin", "library"],
+      "description": "Product surface where the lesson was observed. Same enum as record/scenario/policy."
+    },
+
+    "execution_mode": {
+      "type": "string",
+      "enum": ["bot", "human", "mixed"],
+      "description": "Execution mode of the source dogfood run(s)."
+    },
+
+    "journey_stage": {
+      "type": "string",
+      "enum": [
+        "install",
+        "setup",
+        "first_run",
+        "core_loop",
+        "export",
+        "publish",
+        "recovery",
+        "integration",
+        "verification",
+        "rollout"
+      ],
+      "description": "Where in the product experience the lesson was observed."
+    },
+
+    "issue_kind": {
+      "type": "string",
+      "enum": [
+        "entrypoint_truth",
+        "interface_assumption",
+        "docs_drift",
+        "schema_mismatch",
+        "build_output_mismatch",
+        "flag_contract_mismatch",
+        "evidence_insufficiency",
+        "evidence_overconstraint",
+        "policy_mismatch",
+        "freshness_miscalibration",
+        "read_after_write_timing",
+        "provenance_gap",
+        "execution_mode_mismatch",
+        "surface_misclassification",
+        "ux_discoverability",
+        "verification_gap",
+        "dispatch_format",
+        "concurrency_conflict",
+        "process_lifecycle"
+      ],
+      "description": "What visibly went wrong."
+    },
+
+    "root_cause_kind": {
+      "type": "string",
+      "enum": [
+        "contract_drift",
+        "docs_code_drift",
+        "surface_misclassification",
+        "missing_precondition",
+        "policy_overconstraint",
+        "policy_underconstraint",
+        "build_config_error",
+        "interface_assumption_error",
+        "timing_race",
+        "tooling_gap",
+        "human_process_gap",
+        "schema_alignment_failure",
+        "dispatch_encoding_error",
+        "process_model_mismatch"
+      ],
+      "description": "Why it actually happened."
+    },
+
+    "remediation_kind": {
+      "type": "string",
+      "enum": [
+        "docs_change",
+        "scenario_change",
+        "policy_calibration",
+        "schema_fix",
+        "build_config_fix",
+        "entrypoint_fix",
+        "verification_fix",
+        "classification_fix",
+        "retry_logic",
+        "evidence_requirement_change",
+        "workflow_change",
+        "dispatch_fix",
+        "process_fix"
+      ],
+      "description": "What kind of fix resolved it."
+    },
+
+    "transfer_scope": {
+      "type": "string",
+      "enum": [
+        "repo_local",
+        "surface_local",
+        "surface_archetype",
+        "execution_mode",
+        "org_wide"
+      ],
+      "description": "How far the lesson should travel."
+    },
+
+    "summary": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1000,
+      "description": "1-3 sentence factual description of the lesson. Must read like a precise incident lesson, not a vague insight."
+    },
+
+    "doctrine_statement": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Portable rule derived from this finding. Optional in Phase 1 but included to avoid schema migration later."
+    },
+
+    "notes": {
+      "type": "string",
+      "maxLength": 2000,
+      "description": "Human nuance, context, or caveats."
+    },
+
+    "source_record_ids": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Run IDs of the dogfood records that produced this finding. At least one required."
+    },
+
+    "scenario_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "description": "Scenario IDs relevant to this finding."
+    },
+
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Structured evidence binding. A finding with no evidence is invalid.",
+      "items": {
+        "type": "object",
+        "required": ["evidence_kind"],
+        "additionalProperties": false,
+        "properties": {
+          "evidence_kind": {
+            "type": "string",
+            "enum": [
+              "record",
+              "scenario_result",
+              "ci_check",
+              "policy",
+              "artifact",
+              "doc",
+              "rejection"
+            ],
+            "description": "Type of evidence supporting this finding."
+          },
+          "record_id": {
+            "type": "string",
+            "description": "Run ID of the source record."
+          },
+          "scenario_id": {
+            "type": "string",
+            "description": "Scenario ID if evidence is from a scenario result."
+          },
+          "artifact_ref": {
+            "type": "string",
+            "description": "Path or URL to an artifact."
+          },
+          "policy_ref": {
+            "type": "string",
+            "description": "Path to the policy file."
+          },
+          "doc_ref": {
+            "type": "string",
+            "description": "Path to a documentation file."
+          },
+          "note": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Explanation of what this evidence proves."
+          }
+        }
+      }
+    },
+
+    "fix_refs": {
+      "type": "array",
+      "description": "Links to concrete repair actions taken.",
+      "items": {
+        "type": "object",
+        "required": ["ref_kind", "ref"],
+        "additionalProperties": false,
+        "properties": {
+          "ref_kind": {
+            "type": "string",
+            "enum": ["commit", "pr", "doc", "policy_change", "scenario_change", "workflow_change"],
+            "description": "Type of fix reference."
+          },
+          "ref": {
+            "type": "string",
+            "description": "Commit SHA, PR URL, file path, etc."
+          },
+          "note": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "What the fix did."
+          }
+        }
+      }
+    },
+
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this finding was first authored."
+    },
+
+    "updated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When this finding was last modified."
+    },
+
+    "derived": {
+      "type": "object",
+      "description": "Derivation metadata. Present when the finding was machine-generated by the derivation engine.",
+      "required": ["method", "rule_id", "derived_at", "rationale"],
+      "additionalProperties": false,
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": ["deterministic_rule"],
+          "description": "How this candidate was produced."
+        },
+        "rule_id": {
+          "type": "string",
+          "pattern": "^rule-[a-z0-9][a-z0-9-]*$",
+          "description": "ID of the derivation rule that emitted this finding."
+        },
+        "derived_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the derivation engine produced this candidate."
+        },
+        "rationale": {
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 1000,
+          "description": "Machine-generated explanation of why this candidate was emitted."
+        }
+      }
+    },
+
+    "review": {
+      "type": "object",
+      "description": "Review metadata. Current state of the most recent review action. The full audit trail lives in the review event log.",
+      "additionalProperties": false,
+      "properties": {
+        "reviewed_by": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Actor who performed the review action."
+        },
+        "reviewed_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the review action occurred."
+        },
+        "decision_reason": {
+          "type": "string",
+          "maxLength": 1000,
+          "description": "Why this decision was made."
+        },
+        "review_notes": {
+          "type": "string",
+          "maxLength": 2000,
+          "description": "Additional review context."
+        },
+        "last_action": {
+          "type": "string",
+          "enum": ["review", "accept", "reject", "edit", "merge", "reopen", "invalidate", "supersede"],
+          "description": "The most recent review action taken."
+        },
+        "reject_reason": {
+          "type": "string",
+          "enum": [
+            "insufficient_evidence",
+            "duplicate",
+            "classification_error",
+            "not_portable",
+            "noise",
+            "source_truth_changed",
+            "merged_into_canonical"
+          ],
+          "description": "Structured reject reason. Required when status is rejected."
+        }
+      }
+    },
+
+    "lineage": {
+      "type": "object",
+      "description": "Merge and supersession lineage. Tracks which findings were merged into this one, or which finding superseded this one.",
+      "additionalProperties": false,
+      "properties": {
+        "merged_from": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Finding IDs that were merged into this canonical finding."
+        },
+        "superseded_by": {
+          "type": "string",
+          "description": "Finding ID that supersedes this one. Set when this finding is replaced by a stronger canonical version."
+        }
+      }
+    },
+
+    "invalidation": {
+      "type": "object",
+      "description": "Invalidation metadata. Present when an accepted finding is no longer trustworthy.",
+      "required": ["is_invalidated", "invalidated_at", "reason"],
+      "additionalProperties": false,
+      "properties": {
+        "is_invalidated": {
+          "type": "boolean",
+          "description": "True when this finding has been invalidated."
+        },
+        "invalidated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the finding was invalidated."
+        },
+        "invalidated_by": {
+          "type": "string",
+          "description": "Review event ID that triggered the invalidation."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 5,
+          "maxLength": 1000,
+          "description": "Why this finding is no longer trustworthy."
+        }
+      }
+    }
+  }
+}

package/src/json/dogfood-pattern.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dogfood-lab/testing-os/packages/schemas/src/json/dogfood-pattern.schema.json",
+  "title": "Dogfood Pattern",
+  "description": "A repeated lesson class backed by multiple accepted findings. Patterns represent recurrence, not individual incidents. Only accepted, non-invalidated findings may support a pattern.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "pattern_id",
+    "title",
+    "status",
+    "pattern_kind",
+    "summary",
+    "source_finding_ids",
+    "support",
+    "dimensions",
+    "transfer_scope"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "pattern_id": {
+      "type": "string",
+      "pattern": "^dpat-[a-z0-9][a-z0-9-]*$",
+      "minLength": 6
+    },
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200
+    },
+    "status": {
+      "type": "string",
+      "enum": ["candidate", "accepted", "rejected", "invalidated"]
+    },
+    "pattern_kind": {
+      "type": "string",
+      "enum": [
+        "recurring_failure",
+        "recurring_success",
+        "calibration_signal",
+        "coverage_gap",
+        "verification_seam",
+        "evidence_calibration"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1000
+    },
+    "source_finding_ids": {
+      "type": "array",
+      "minItems": 2,
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Finding IDs that support this pattern. Minimum 2."
+    },
+    "support": {
+      "type": "object",
+      "required": ["finding_count", "repo_count"],
+      "additionalProperties": false,
+      "properties": {
+        "finding_count": { "type": "integer", "minimum": 2 },
+        "repo_count": { "type": "integer", "minimum": 1 },
+        "surface_count": { "type": "integer", "minimum": 1 },
+        "execution_modes": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["bot", "human", "mixed"] }
+        }
+      }
+    },
+    "dimensions": {
+      "type": "object",
+      "required": ["issue_kinds"],
+      "additionalProperties": false,
+      "properties": {
+        "product_surfaces": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["cli", "desktop", "web", "api", "mcp-server", "npm-package", "plugin", "library"] }
+        },
+        "issue_kinds": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "root_cause_kinds": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "remediation_kinds": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "transfer_scope": {
+      "type": "string",
+      "enum": ["repo_local", "surface_local", "surface_archetype", "execution_mode", "org_wide"]
+    },
+    "pattern_strength": {
+      "type": "string",
+      "enum": ["emerging", "strong", "portfolio_stable"]
+    },
+    "lineage_note": {
+      "type": "string",
+      "maxLength": 1000
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reviewed_by": { "type": "string" },
+        "reviewed_at": { "type": "string", "format": "date-time" },
+        "decision_reason": { "type": "string", "maxLength": 1000 },
+        "last_action": { "type": "string", "enum": ["accept", "reject", "edit", "invalidate"] }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  }
+}

package/src/json/dogfood-recommendation.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dogfood-lab/testing-os/packages/schemas/src/json/dogfood-recommendation.schema.json",
+  "title": "Dogfood Recommendation",
+  "description": "Actionable guidance for future repos, surfaces, or execution modes. Derived from accepted patterns. Narrower and more operational than doctrine.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "recommendation_id",
+    "title",
+    "status",
+    "recommendation_kind",
+    "summary",
+    "applies_to",
+    "based_on_pattern_ids",
+    "action"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "recommendation_id": {
+      "type": "string",
+      "pattern": "^drec-[a-z0-9][a-z0-9-]*$",
+      "minLength": 6
+    },
+    "title": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 200
+    },
+    "status": {
+      "type": "string",
+      "enum": ["candidate", "accepted", "rejected"]
+    },
+    "recommendation_kind": {
+      "type": "string",
+      "enum": [
+        "starter_scenario",
+        "starter_check",
+        "policy_seed",
+        "evidence_expectation",
+        "review_prompt",
+        "verification_rule"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 1000
+    },
+    "applies_to": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "product_surfaces": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["cli", "desktop", "web", "api", "mcp-server", "npm-package", "plugin", "library"] }
+        },
+        "execution_modes": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["bot", "human", "mixed"] }
+        },
+        "transfer_scope": {
+          "type": "string",
+          "enum": ["repo_local", "surface_local", "surface_archetype", "execution_mode", "org_wide"]
+        }
+      }
+    },
+    "based_on_pattern_ids": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "action": {
+      "type": "object",
+      "required": ["type", "details"],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["add_check", "add_scenario", "set_policy", "set_evidence", "add_review_step", "set_verification"]
+        },
+        "target": { "type": "string", "maxLength": 100 },
+        "details": { "type": "string", "minLength": 5, "maxLength": 1000 }
+      }
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["emerging", "strong", "proven"]
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "reviewed_by": { "type": "string" },
+        "reviewed_at": { "type": "string", "format": "date-time" },
+        "decision_reason": { "type": "string", "maxLength": 1000 },
+        "last_action": { "type": "string", "enum": ["accept", "reject", "edit"] }
+      }
+    },
+    "created_at": { "type": "string", "format": "date-time" },
+    "updated_at": { "type": "string", "format": "date-time" }
+  }
+}