{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://quailpages.com/schema/qp.site-discovery-interview.json",
  "title": "Quail Pages Site Discovery Interview Contract",
  "description": "Describes an adaptive method for improving a Site Discovery Knowledge Contract. Begin by understanding what already exists: the current website or public presence, the relationship of the proposed work to that existing state, and the organizational identity and source material that may already answer discovery questions. Ask only when the answer can materially change what comes next. The interview seeks sufficient starting context, never permission to proceed or exhaustive field completion.",
  "$comment": "Authoritative guidance: Facts first. Expression second. Ask only when the answer can materially change what comes next. Discovery seeks sufficiency, not completeness. Before asking the user to restate information, orient to supplied context and determine whether a website, brand, content system, organizational story, or other relevant public presence already exists. Understand whether the work is greenfield, a reskin, redesign, rebrand, migration/port, restructuring, replacement, or a combination, and what should be preserved, changed, migrated, or deliberately left behind. Also understand existing organizational truth—what the organization does, why it exists, its mission or purpose, vision, values, story, positioning, terminology, and voice—without forcing formal corporate artifacts where none exist. Distinguish established constraints from preferences and references, and use authoritative supplied sources rather than making the human repeat knowledge already sufficiently established. Questions improve knowledge; they do not perform creative direction, recommend themes, propose pages, generate QP documents, score readiness, or gate downstream work.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "version": {
      "const": "0.1",
      "description": "Identifies the V0.1 interview vocabulary when a producer chooses to record a version."
    },
    "knowledgeContract": {
      "const": "https://quailpages.com/schema/qp.site-discovery.json",
      "description": "Identifies the separate knowledge contract this interview is intended to improve."
    },
    "purpose": {
      "type": "string",
      "minLength": 1,
      "description": "A concise explanation of why this interview is being conducted."
    },
    "principles": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true,
      "description": "Human-readable operating guidance. This is not a condition or scoring language."
    },
    "stages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/stage"
      },
      "description": "Optional interview stages. Their order guides inquiry but does not require every stage or field to be completed."
    },
    "questions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/question"
      },
      "description": "Candidate questions selected adaptively according to what is already known and what could materially change subsequent work."
    },
    "selectionPolicy": {
      "$ref": "#/$defs/selectionPolicy"
    },
    "synthesis": {
      "$ref": "#/$defs/synthesis"
    },
    "stoppingPolicy": {
      "$ref": "#/$defs/stoppingPolicy"
    }
  },
  "$defs": {
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    },
    "stringList": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/nonEmptyString"
      },
      "uniqueItems": true
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
    },
    "knowledgePath": {
      "type": "string",
      "pattern": "^(|/.*)$",
      "description": "JSON Pointer into a separate Site Discovery Knowledge Contract."
    },
    "stageName": {
      "enum": [
        "context-ingestion",
        "organization-and-mandate",
        "people-and-visit-situations",
        "actions-beliefs-and-objections",
        "differentiation-truth-and-proof",
        "materials",
        "operational-requirements",
        "identity-and-creative-authority",
        "character-and-references",
        "synthesis"
      ],
      "description": "Discovery stages establish reasoning dependencies rather than a mandatory questionnaire. context-ingestion first orients to existing state and supplied sources, including whether the work is greenfield, reskin, redesign, rebrand, migration/port, restructuring, replacement, or a combination. organization-and-mandate establishes what the organization does, what the project must change, and consequential organizational truth such as purpose, mission, vision, values, story, positioning, and meaningful differentiation when known or materially useful. identity-and-creative-authority distinguishes what is established and must be preserved from what may be clarified, reinterpreted, or newly created. character-and-references interprets meaningful references by learning which qualities should carry forward and which should not when that distinction could materially affect later work."
    },
    "stage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/stageName"
        },
        "goal": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "guidance": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "question": {
      "type": "object",
      "description": "One candidate inquiry. Conditions are plain-language guidance for an AI consumer, not an executable generalized condition language. Build on available context rather than asking the user to repeat information already sufficiently established by an appropriate source. When existing-state orientation is unresolved and consequential, clarify what already exists, the intended relationship of the new work to it, what should be preserved or changed, and how much freedom exists to reinterpret organizational story, content, identity, or voice.",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/id"
        },
        "stage": {
          "$ref": "#/$defs/stageName"
        },
        "goal": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "prompt": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "targets": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/knowledgePath"
          },
          "uniqueItems": true
        },
        "importance": {
          "enum": [
            "high",
            "medium",
            "low"
          ]
        },
        "askWhen": {
          "$ref": "#/$defs/nonEmptyString",
          "description": "Plain-language evidence that this question could materially change what comes next."
        },
        "skipWhen": {
          "$ref": "#/$defs/nonEmptyString",
          "description": "Plain-language evidence that the answer is already sufficient or would not affect subsequent work."
        },
        "weakAnswerSignals": {
          "$ref": "#/$defs/stringList",
          "description": "Signals such as generic claims, audience 'everyone', unexplained references, unclear relationship to an existing site or brand, generic mission/vision/value language that does not reveal actual organizational behavior or belief, or assertions without observable behavior or evidence."
        },
        "followUps": {
          "$ref": "#/$defs/stringList",
          "description": "Possible follow-up prompts. They remain optional and are used only when they can materially improve consequential knowledge."
        },
        "completion": {
          "$ref": "#/$defs/nonEmptyString",
          "description": "Plain-language indication that this line of inquiry is sufficient for the present work."
        }
      }
    },
    "selectionPolicy": {
      "type": "object",
      "description": "Priorities for choosing the next useful question without turning discovery into a score or completeness gate. Existing-state uncertainty is consequential when misunderstanding whether the work is greenfield, reskin, redesign, rebrand, migration/port, restructuring, or replacement could cause later work to preserve, discard, rewrite, or invent the wrong things. Organizational-identity uncertainty is consequential when insufficient understanding of purpose, story, voice, values, positioning, or established language would materially weaken later content or creative work.",
      "additionalProperties": false,
      "properties": {
        "priorityOrder": {
          "type": "array",
          "items": {
            "enum": [
              "high-impact-conflict",
              "blocking-unknown",
              "unsupported-important-claim",
              "operational-constraint",
              "identity-boundary",
              "character-uncertainty"
            ]
          },
          "uniqueItems": true
        },
        "guidance": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "synthesis": {
      "type": "object",
      "description": "Guidance for reflecting the current knowledge back to the user while preserving sources, assumptions, conflicts, and unknowns. Preserve distinctions between current-state facts and desired future state; between organizational truth and marketing invention; and between material that must be preserved, material that may be reinterpreted, and greenfield areas open to later creative work.",
      "additionalProperties": false,
      "properties": {
        "include": {
          "$ref": "#/$defs/stringList"
        },
        "guidance": {
          "$ref": "#/$defs/stringList"
        }
      }
    },
    "stoppingPolicy": {
      "type": "object",
      "description": "A sufficiency-oriented stopping policy. It must not require every discovery field and must not be interpreted as permission to proceed. Missing formal mission, vision, values, brand artifacts, or an existing website is not itself a reason to continue questioning. Continue only when unresolved existing-state or organizational-identity knowledge could materially change subsequent work.",
      "additionalProperties": false,
      "properties": {
        "signals": {
          "$ref": "#/$defs/stringList"
        },
        "guidance": {
          "$ref": "#/$defs/stringList"
        }
      }
    }
  }
}