Add construct_block / construct_item tags on dim_question

[countercheck]

Summary

• Two optional authored text attributes (construct_block, construct_item) on the survey JSON flow through int_survey_questions to new columns on dim_question, marking questions that belong to a reusable scale (PHQ-9, GAD-7, eNPS, …).
• Provenance only — not a pooling key. Cross-survey / cross-version pooling stays the explicit parent_question_id opt-in (invariant 5); §4.10 records that decision.
• Publish-gate validation lints shape and the block/item co-occurrence, and rejects construct_item on a matrix / paneldynamic container (an item identifies a leaf, not the container that groups leaves).
• New singular dbt test construct_pair_integrity backstops the warehouse-side invariant against backdoor inserts.

Authoring shape

// plain question
{ "type": "radiogroup", "name": "q1", "construct_block": "enps", "construct_item": "enps_q1", "choices": [...] }

// scale-in-a-matrix: block on the matrix, item on each row (block inherits)
{ "type": "matrix", "name": "phq9", "construct_block": "phq9",
  "rows": [{ "value": "q1", "construct_item": "phq9_q1" }, ...],
  "columns": [...] }

Test plan

• uv run ruff check . && uv run ruff format .
• uv run mypy api/
• python3 scripts/check_invariants.py — all 4 invariant checks clean
• uv run pytest — 435/435 passing (incl. 13 new construct-tag tests)
• dbt build — 59/59 models + tests passing (incl. the new construct_pair_integrity singular test)
• Author a survey with construct tags and confirm dim_question.construct_block / construct_item populate as expected end-to-end

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds optional construct provenance tags (construct_block, construct_item) to flow from authored SurveyJS JSON through dbt staging into the dim_question mart, with publish-time validation and a warehouse-side integrity test. This supports identifying questions that belong to reusable scales (e.g., PHQ-9, GAD-7) without changing the explicit cross-survey/version pooling mechanism (parent_question_id).

Changes:

• Add publish-gate validation + unit tests to enforce construct tag shape, container/leaf placement rules, and block/item co-occurrence.
• Extend dbt intermediate + mart models to propagate construct tags into dim_question, and document the new columns.
• Add a dbt singular test to enforce construct_item ⇒ construct_block integrity.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
survey-engine-design-doc.md	Documents new dim_question columns and clarifies “provenance only” (not a pooling key).
dbt/tests/singular/construct_pair_integrity.sql	Adds singular test asserting construct_item is never present without construct_block.
dbt/models/marts/dim_question.sql	Adds construct_block/construct_item columns to the stable question dimension.
dbt/models/marts/_marts.yml	Documents the two new dim_question columns for analysts.
dbt/models/intermediate/int_survey_questions.sql	Extracts construct tags from definition JSON, including inheritance for matrix/paneldynamic leaves.
api/tests/test_publish_gate.py	Adds publish-gate tests covering construct tag acceptance/rejection cases.
api/survey_engine/validation.py	Implements publish-time validation for construct tag type, placement, and inheritance rules.