skills/closing-bible/references/families.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "closing-bible families (families.json)",
  "description": "PRD §4 'Source census': 'Group … potential document families by title, parties, date, version indicators and substantive similarity.' A family is one document across its versions and duplicates. Produced by script from the manifest alone (hash groups, then normalised title_hint, then sigpack agreement names and checklist rows when supplied). Every distinct manifest id appears in exactly one family; the script refuses to write otherwise. Shown to the user at Gate 1, who may split or merge; the confirmed file is what reconciliation reads.",
  "type": "object",
  "required": ["schema_version", "corpus_id", "checklist_sha256", "families", "counts"],
  "additionalProperties": false,
  "properties": {
    "schema_version": { "const": "1.0.0" },
    "corpus_id": { "type": "string" },
    "checklist_sha256": { "type": ["string", "null"], "description": "sha256 of the checklist.json bytes the families were bound against; null when none was supplied. Reconciliation refuses a checklist whose hash differs, and refuses a checklist when this is null: rows bound at the families stage must be the rows reconciled, so run families with the same --checklist first." },
    "families": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["family_id", "title_hint", "grouping_basis", "member_ids", "sigpack_agreement", "checklist_ref"],
        "additionalProperties": false,
        "properties": {
          "family_id": { "type": "string", "pattern": "^fam_[0-9a-f]{12}$", "description": "sha256 over the sorted member ids, first 12 hex. Same members, same id, across runs." },
          "title_hint": { "type": "string" },
          "grouping_basis": { "type": "array", "minItems": 1, "items": { "enum": ["hash", "normalised-title", "sigpack-agreement", "checklist-ref", "user-regrouped"] } },
          "member_ids": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^sha256:[0-9a-f]{12}$" } },
          "sigpack_agreement": { "type": ["string", "null"], "description": "The sigpack ledger agreement this family matched, when a current ledger was supplied and a member's path equals a ledger signature_pages[].file." },
          "checklist_ref": { "type": ["string", "null"], "description": "The user checklist row this family matched, when a checklist was supplied." }
        }
      }
    },
    "counts": {
      "type": "object",
      "required": ["distinct_documents", "families", "in_families"],
      "additionalProperties": false,
      "properties": {
        "distinct_documents": { "type": "integer", "minimum": 0 },
        "families": { "type": "integer", "minimum": 0 },
        "in_families": { "type": "integer", "minimum": 0, "description": "Must equal distinct_documents." }
      }
    }
  }
}