@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/contract-test.py.template

@@ -0,0 +1,384 @@
+"""
+{{SOURCE_NAME}} Contract Tests
+
+Validates alignment between the golden sample payload, ingestion model,
+display DTO, and (optionally) TypeScript types.
+
+Supports two modes for schema drift detection:
+  - SOFT (default while schema evolves): warnings.warn — CI passes
+  - HARD (after schema freeze): assert — CI blocks on drift
+
+Freeze mode resolution precedence:
+    1) CONTRACT_SCHEMA_FROZEN env var (explicit override)
+    2) Marker file tests/fixtures/payloads/{{source_slug}}/_contract_state.json
+    3) CI fallback (if CI=true and sample exists): HARD mode
+    4) Default: SOFT mode
+
+Accepted explicit values: 1/true/yes/on/frozen and 0/false/no/off/evolving.
+
+Run: pytest tests/unit/test_contract_{{source_slug}}.py -v
+
+Part of the data contract pipeline — these tests ARE the contract.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import warnings
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Union, get_args, get_origin, get_type_hints
+
+import pytest
+from pydantic import BaseModel
+
+# --- Update these imports to match your project ---
+# from src.models.ingestion.{{source_slug}} import {{ClassName}}Payload
+# from src.models.responses.{{source_slug}} import {{ClassName}}Response
+# from src.services.normalizers.{{source_slug}} import normalize
+
+PAYLOAD_DIR = Path(__file__).parent.parent / "fixtures" / "payloads"
+SAMPLE_PATH = PAYLOAD_DIR / "{{source_slug}}" / "sample.json"
+STATE_PATH = PAYLOAD_DIR / "{{source_slug}}" / "_contract_state.json"
+
+# ---------------------------------------------------------------------------
+# Schema evolution toggle
+# ---------------------------------------------------------------------------
+# Set to True once the upstream schema is stable. While False, drift
+# detection emits warnings; when True, drift causes hard test failures.
+#
+# Prefer explicit env override in CI:
+#   CONTRACT_SCHEMA_FROZEN=1   -> hard mode
+#   CONTRACT_SCHEMA_FROZEN=0   -> soft mode
+#
+# If env is missing, _resolve_schema_frozen() applies fallback logic.
+
+
+def _truthy_env(value: str) -> bool | None:
+    """Parse common truthy/falsey strings; return None if unknown."""
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "on", "frozen", "hard"}:
+        return True
+    if normalized in {"0", "false", "no", "off", "evolving", "soft"}:
+        return False
+    return None
+
+
+def _load_state_file_flag() -> bool | None:
+    """Read optional schema-frozen flag from _contract_state.json.
+
+    Expected shape:
+    {
+      "schema_frozen": true,
+      "source": "agent",
+      "note": "optional"
+    }
+    """
+    if not STATE_PATH.exists():
+        return None
+    try:
+        state = json.loads(STATE_PATH.read_text(encoding="utf-8"))
+        value = state.get("schema_frozen")
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return _truthy_env(value)
+    except Exception as exc:  # pragma: no cover - defensive fallback
+        warnings.warn(
+            f"Could not parse contract state file {STATE_PATH}: {exc}. "
+            "Falling back to next freeze resolution rule.",
+            stacklevel=2,
+        )
+    return None
+
+
+def _resolve_schema_frozen() -> bool:
+    """Resolve drift mode using explicit override + deterministic fallbacks."""
+    env_value = os.getenv("CONTRACT_SCHEMA_FROZEN")
+    if env_value is not None:
+        parsed = _truthy_env(env_value)
+        if parsed is not None:
+            return parsed
+        warnings.warn(
+            "CONTRACT_SCHEMA_FROZEN has unrecognized value "
+            f"'{env_value}'. Expected one of: 1/0, true/false, frozen/evolving. "
+            "Continuing with fallback resolution.",
+            stacklevel=2,
+        )
+
+    state_flag = _load_state_file_flag()
+    if state_flag is not None:
+        return state_flag
+
+    ci_value = os.getenv("CI", "")
+    ci_mode = _truthy_env(ci_value) is True
+    if ci_mode and SAMPLE_PATH.exists():
+        warnings.warn(
+            "Auto-freeze fallback enabled (CI=true, sample.json present, no explicit "
+            "CONTRACT_SCHEMA_FROZEN/state flag). Running HARD drift mode. "
+            "Set CONTRACT_SCHEMA_FROZEN explicitly to override.",
+            stacklevel=2,
+        )
+        return True
+
+    return False
+
+
+SCHEMA_FROZEN = _resolve_schema_frozen()
+
+# ---------------------------------------------------------------------------
+# Exclusion allow-list  (Layer 3 of the three-layer defence)
+# ---------------------------------------------------------------------------
+# Keys that are intentionally NOT typed in the DTO.  Use dot-path globs
+# (fnmatch syntax).  Always add a comment with a ticket ref or justification.
+# Review periodically — remove entries once the key is typed or removed upstream.
+KNOWN_EXCLUDED_KEYS: dict[str, set[str]] = {
+    # Example entries (delete and replace with real ones):
+    # "root.section.*": {"experimental_field"},  # TICKET-123: upstream experiment
+    # "surveys.*": {"internal_metadata"},         # TICKET-456: not consumer-facing
+}
+
+
+# ====================== helpers =============================================
+
+def _unwrap_optional(tp):
+    """Extract T from Optional[T] / T | None."""
+    origin = get_origin(tp)
+    if origin is Union:
+        args = [a for a in get_args(tp) if a is not type(None)]
+        return args[0] if len(args) == 1 else tp
+    return tp
+
+
+def _resolve_child(tp):
+    """If tp is list[X] return X; if BaseModel subclass, return it; else None."""
+    tp = _unwrap_optional(tp)
+    if isinstance(tp, type) and issubclass(tp, BaseModel):
+        return tp
+    origin = get_origin(tp)
+    if origin is list:
+        inner = get_args(tp)[0]
+        inner = _unwrap_optional(inner)
+        if isinstance(inner, type) and issubclass(inner, BaseModel):
+            return inner
+    return None
+
+
+def _collect_dropped_keys(
+    data,
+    model_cls: type[BaseModel],
+    prefix: str = "",
+    dropped: list[str] | None = None,
+) -> list[str]:
+    """Recursively walk JSON data vs model fields; return unmatched key paths.
+
+    Walks nested dicts and lists-of-dicts at every depth level, not just
+    top-level keys.  Keys matching KNOWN_EXCLUDED_KEYS are silently skipped.
+    """
+    if dropped is None:
+        dropped = []
+
+    if isinstance(data, list):
+        for item in data:
+            if isinstance(item, dict):
+                _collect_dropped_keys(item, model_cls, prefix, dropped)
+        return dropped
+
+    if not isinstance(data, dict):
+        return dropped
+
+    hints = get_type_hints(model_cls, include_extras=True)
+    alias_map: dict[str, tuple[str, type | None]] = {}
+    for field_name, field_info in model_cls.model_fields.items():
+        alias = field_info.alias or field_name
+        alias_map[alias] = (field_name, hints.get(field_name))
+
+    for key in data:
+        full_path = f"{prefix}.{key}" if prefix else key
+
+        # Check exclusion allow-list
+        if any(
+            fnmatch(full_path, pattern) and key in excl
+            for pattern, excl in KNOWN_EXCLUDED_KEYS.items()
+        ):
+            continue
+
+        if key not in alias_map:
+            dropped.append(full_path)
+        else:
+            _field_name, type_hint = alias_map[key]
+            if type_hint is not None:
+                child_model = _resolve_child(type_hint)
+                if child_model is not None:
+                    _collect_dropped_keys(
+                        data[key], child_model, full_path, dropped,
+                    )
+
+    return dropped
+
+
+def _report_drift(dropped: list[str], context: str) -> None:
+    """Emit soft warning or hard assertion depending on SCHEMA_FROZEN."""
+    if not dropped:
+        return
+
+    msg = (
+        f"Coverage gap in {context} — "
+        f"{len(dropped)} key(s) forwarded via model_extra:\n"
+        + "\n".join(f"  - {k}" for k in dropped)
+        + "\nData is NOT lost (extra='allow'), but typed fields "
+        "give IDE support and validation."
+    )
+
+    if SCHEMA_FROZEN:
+        raise AssertionError(msg)
+    else:
+        warnings.warn(msg, stacklevel=2)
+
+
+# ====================== fixtures ============================================
+
+@pytest.fixture
+def golden_sample() -> dict:
+    """Load the golden sample payload."""
+    assert SAMPLE_PATH.exists(), (
+        f"Golden sample missing: {SAMPLE_PATH}\n"
+        "Create one by copying a real payload and sanitizing PII."
+    )
+    return json.loads(SAMPLE_PATH.read_text(encoding="utf-8"))
+
+
+# ============================================================
+# D8 — Golden Sample Exists
+# ============================================================
+
+class TestGoldenSampleExists:
+    """Verify the golden sample fixture is present and loadable."""
+
+    def test_sample_file_exists(self):
+        assert SAMPLE_PATH.exists(), f"Golden sample not found: {SAMPLE_PATH}"
+
+    def test_sample_is_valid_json(self):
+        data = json.loads(SAMPLE_PATH.read_text(encoding="utf-8"))
+        assert isinstance(data, (dict, list)), "Golden sample must be a JSON object or array"
+
+
+# ============================================================
+# D1 — Payload Keys Covered by Ingestion Model (Recursive)
+# ============================================================
+
+class TestPayloadToIngestionModel:
+    """Every key in the golden sample must map to an ingestion model field.
+
+    Uses _collect_dropped_keys for recursive depth comparison, not just
+    top-level set difference.
+    """
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_all_payload_keys_covered(self, golden_sample):
+        """No payload key should be missing from the ingestion model."""
+        # from src.models.ingestion.{{source_slug}} import {{ClassName}}Payload
+
+        dropped = _collect_dropped_keys(golden_sample, {{ClassName}}Payload)
+        _report_drift(dropped, "payload → ingestion model")
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_payload_validates_against_ingestion_model(self, golden_sample):
+        """Golden sample must parse into the ingestion model without error."""
+        # from src.models.ingestion.{{source_slug}} import {{ClassName}}Payload
+
+        result = {{ClassName}}Payload.model_validate(golden_sample)
+        assert result is not None
+
+
+# ============================================================
+# D3 — Display DTO Extra Config
+# ============================================================
+
+class TestDtoConfig:
+    """Display DTO must not use extra='ignore'."""
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_dto_does_not_ignore_extras(self):
+        """extra='ignore' silently drops fields — use 'forbid' or 'allow'."""
+        # from src.models.responses.{{source_slug}} import {{ClassName}}Response
+
+        extra_config = {{ClassName}}Response.model_config.get("extra", "ignore")
+        assert extra_config != "ignore", (
+            f"Display DTO uses extra='ignore' — this silently drops fields. "
+            f"Use extra='forbid' (strict) or extra='allow' (migration)."
+        )
+
+
+# ============================================================
+# D2 — Display DTO Covers Ingestion Fields (Recursive)
+# ============================================================
+
+class TestIngestionToDto:
+    """Ingestion model fields should map to display DTO fields.
+
+    Uses _collect_dropped_keys for recursive depth comparison.
+    """
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_golden_sample_validates_against_dto(self, golden_sample):
+        """Golden sample must parse into the display DTO without error."""
+        # from src.models.responses.{{source_slug}} import {{ClassName}}Response
+
+        result = {{ClassName}}Response.model_validate(golden_sample)
+        assert result is not None
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_no_uncovered_payload_keys_in_dto(self, golden_sample):
+        """Every payload key must have a corresponding DTO field."""
+        # from src.models.responses.{{source_slug}} import {{ClassName}}Response
+
+        dropped = _collect_dropped_keys(golden_sample, {{ClassName}}Response)
+        _report_drift(dropped, "payload → display DTO")
+
+
+# ============================================================
+# D10 — Normalizer Produces Valid DTO
+# ============================================================
+
+class TestNormalizer:
+    """Normalizer output must validate against the display DTO."""
+
+    @pytest.mark.skip(reason="Uncomment imports and remove skip to activate")
+    def test_normalizer_output_is_valid_dto(self, golden_sample):
+        """Pass golden sample through normalizer → must produce valid DTO."""
+        # from src.models.ingestion.{{source_slug}} import {{ClassName}}Payload
+        # from src.services.normalizers.{{source_slug}} import normalize
+
+        ingestion = {{ClassName}}Payload.model_validate(golden_sample)
+        dto = normalize(ingestion)
+        assert dto is not None
+        # Verify it's actually the right type
+        # assert isinstance(dto, {{ClassName}}Response)
+
+
+# ============================================================
+# D4 — DTO Aliases Match TypeScript (Manual Check)
+# ============================================================
+
+class TestTypeScriptAlignment:
+    """
+    Cross-layer check: DTO aliases should match TypeScript interface properties.
+
+    This is a structural reminder test. For automated checking,
+    use the ts_dto_compare.py script.
+    """
+
+    @pytest.mark.skip(reason="Run scripts/ts_dto_compare.py for automated check")
+    def test_dto_aliases_documented(self):
+        """Ensure DTO aliases are listed for manual comparison."""
+        # from src.models.responses.{{source_slug}} import {{ClassName}}Response
+
+        aliases = {
+            info.alias or name
+            for name, info in {{ClassName}}Response.model_fields.items()
+        }
+        # Print for manual comparison with TypeScript interface
+        print(f"DTO aliases: {sorted(aliases)}")
+        assert len(aliases) > 0, "DTO has no fields"

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/display-dto.py.template

@@ -0,0 +1,39 @@
+"""
+{{SOURCE_NAME}} Display DTO
+
+Frozen Pydantic model defining the API boundary contract for {{source_name}} data.
+This is what the frontend receives — changes here require frontend coordination.
+
+Part of the data contract pipeline:
+  Source → Adapter → Ingestion Model → Normalizer → **Display DTO** → API Router
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class {{ClassName}}Response(BaseModel):
+    """
+    API response DTO for {{source_name}}.
+
+    Rules:
+    - frozen=True: immutable after construction
+    - populate_by_name=True: can construct with Python names or aliases
+    - extra="forbid": unknown fields cause ValidationError (no silent drops)
+    - Every field has Field(alias="camelCaseName") for frontend consumption
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        populate_by_name=True,
+        extra="forbid",
+    )
+
+    # --- Replace these with actual display fields ---
+    # Example fields (delete and replace):
+    # record_id: str = Field(alias="recordId")
+    # score: float = Field(alias="score")
+    # total_responses: int = Field(alias="totalResponses")
+    # categories: list[str] = Field(default_factory=list, alias="categories")
+    {{FIELDS}}

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/frontend-service.ts.template

@@ -0,0 +1,46 @@
+/**
+ * {{SOURCE_NAME}} Frontend Service
+ *
+ * Typed fetch functions for {{source_name}} API endpoints.
+ * Return types match the TypeScript interfaces in types/{{source-slug}}.ts.
+ *
+ * Part of the data contract pipeline:
+ *   Backend API Router → **Frontend Service** → UI Components
+ */
+
+import type { {{ClassName}}Response } from '@/types/{{source-slug}}';
+// Use your project's API client — adapt the import to match:
+// import { apiClient } from '@/lib/api-client';
+// import axios from 'axios';
+
+const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? '';
+
+/**
+ * Fetch {{source_name}} data from the API.
+ *
+ * @returns Typed {{ClassName}}Response from the backend.
+ * @throws Error if the request fails.
+ */
+export async function fetch{{ClassName}}Data(): Promise<{{ClassName}}Response> {
+  const response = await fetch(`${BASE_URL}/api/{{url-slug}}`);
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch {{source_name}} data: ${response.status} ${response.statusText}`
+    );
+  }
+
+  const data: {{ClassName}}Response = await response.json();
+  return data;
+}
+
+// --- React Query hook example (uncomment if using TanStack Query) ---
+//
+// import { useQuery } from '@tanstack/react-query';
+//
+// export function use{{ClassName}}Data() {
+//   return useQuery({
+//     queryKey: ['{{source-slug}}'],
+//     queryFn: fetch{{ClassName}}Data,
+//   });
+// }

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/frontend-types.ts.template

@@ -0,0 +1,38 @@
+/**
+ * {{SOURCE_NAME}} TypeScript Types
+ *
+ * TypeScript interfaces mirroring the backend display DTO.
+ * Field names match the DTO's camelCase aliases exactly.
+ *
+ * Part of the data contract pipeline:
+ *   Backend Display DTO → **Frontend Types** → Frontend Service
+ *
+ * IMPORTANT: When adding/removing fields in the Python DTO,
+ * update this file in the same PR.
+ */
+
+// --- Replace with actual interface matching the display DTO ---
+
+export interface {{ClassName}}Response {
+  // Each property name matches the Python Field(alias="...") value.
+  // Types follow the Python→TypeScript mapping:
+  //   str → string
+  //   int/float → number
+  //   bool → boolean
+  //   list[T] → T[]
+  //   dict[str, T] → Record<string, T>
+  //   Optional[T] → T | null
+
+  // Example fields (delete and replace):
+  // recordId: string;
+  // score: number;
+  // totalResponses: number;
+  // categories: string[];
+  {{FIELDS}}
+}
+
+// --- Nested interfaces (if the DTO has nested objects) ---
+
+// export interface {{NestedName}} {
+//   nestedField: string;
+// }

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/ingestion-model.py.template

@@ -0,0 +1,42 @@
+"""
+{{SOURCE_NAME}} Ingestion Model
+
+1:1 Pydantic model matching the raw {{source_name}} payload shape.
+This model exists to validate raw data structure — no business logic.
+
+Part of the data contract pipeline:
+  Source → [Adapter] → **Ingestion Model** → [Normalizer] → Display DTO
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Shared config for all data-ingest DTOs.  extra="allow" means unknown JSON
+# keys land in model_extra and flow through to .model_dump() output — nothing
+# is silently dropped while the upstream schema is still evolving.
+# Switch individual models to extra="forbid" only AFTER the schema is frozen.
+_FLEX = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class {{ClassName}}Payload(BaseModel):
+    """
+    1:1 representation of the raw {{source_name}} payload.
+
+    - Every key in the source payload has a corresponding field here.
+    - Field types match the source data types exactly.
+    - Uses _FLEX (extra="allow") so new upstream keys pass through
+      via model_extra instead of being silently dropped.
+    - When the schema is frozen, swap _FLEX → ConfigDict(extra="forbid").
+    """
+
+    model_config = _FLEX
+
+    # --- Replace these with actual fields from the source payload ---
+    # Example fields (delete and replace):
+    # record_id: str
+    # score: float
+    # responses: int
+    # categories: list[str] = Field(default_factory=list)
+    # metadata: dict | None = None
+    {{FIELDS}}

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/mapping-doc.md.template

@@ -0,0 +1,46 @@
+# {{SOURCE_NAME}} — UI ↔ JSON Data Mapping
+
+> **Auto-generated reference** — do not hand-edit.
+> Regenerate with: `python scripts/generate_mapping_doc.py`
+> Source of truth: contract tests in `tests/unit/test_contract_{{source_slug}}.py`
+
+---
+
+## Data Source
+
+| Property | Value |
+|----------|-------|
+| Source Type | {{source_type}} |
+| Source Location | {{source_location}} |
+| Golden Sample | `tests/fixtures/payloads/{{source_slug}}/sample.json` |
+| Ingestion Model | `src/models/ingestion/{{source_slug}}.py` |
+| Display DTO | `src/models/responses/{{source_slug}}.py` |
+| API Endpoint | `GET /api/{{url-slug}}` |
+| Frontend Types | `frontend/src/types/{{source-slug}}.ts` |
+| Frontend Service | `frontend/src/services/{{source-slug}}.ts` |
+
+---
+
+## Field Mapping
+
+| JSON Key | Python Field | DTO Alias | TypeScript Property | Type | Notes |
+|----------|-------------|-----------|--------------------:|------|-------|
+{{FIELD_ROWS}}
+
+---
+
+## Intentionally Dropped Fields
+
+Fields present in the source but NOT exposed to the frontend:
+
+| JSON Key | Reason |
+|----------|--------|
+{{DROPPED_ROWS}}
+
+---
+
+## Changelog
+
+| Date | Change | Author |
+|------|--------|--------|
+| {{DATE}} | Initial mapping generated | {{AGENT}} |

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/normalizer.py.template

@@ -0,0 +1,48 @@
+"""
+{{SOURCE_NAME}} Normalizer
+
+Transforms the raw ingestion model into the display DTO.
+Business logic (renaming, computing, filtering) lives here — not in the adapter or DTO.
+
+Part of the data contract pipeline:
+  Source → Adapter → Ingestion Model → **Normalizer** → Display DTO → API Router
+"""
+
+from loguru import logger
+
+from src.models.ingestion.{{source_slug}} import {{ClassName}}Payload
+from src.models.responses.{{source_slug}} import {{ClassName}}Response
+
+
+def normalize(raw: {{ClassName}}Payload) -> {{ClassName}}Response:
+    """
+    Transform raw {{source_name}} payload into display DTO.
+
+    Every field mapping is explicit. If a field is intentionally dropped
+    from the display DTO, document WHY with a comment.
+
+    Args:
+        raw: Validated ingestion model instance.
+
+    Returns:
+        Frozen display DTO ready for API serialization.
+    """
+    return {{ClassName}}Response(
+        # --- Direct mappings ---
+        # record_id=raw.record_id,
+        # score=raw.score,
+
+        # --- Computed fields ---
+        # total_responses=_compute_total(raw),
+
+        # --- Intentionally dropped fields ---
+        # raw.internal_id — not exposed to frontend (internal tracking only)
+        {{FIELD_MAPPINGS}}
+    )
+
+
+# --- Helper functions for computed fields ---
+
+# def _compute_total(raw: {{ClassName}}Payload) -> int:
+#     """Compute total from raw components."""
+#     return sum(raw.component_counts)

package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/assets/prompts/extract_requirements.md

@@ -0,0 +1,36 @@
+# Sub-prompt: Extract Requirements
+
+Use this prompt to extract field-level requirements from PRDs, tickets, or docs.
+Paste the document content after the divider, then run this prompt.
+
+---
+
+You are extracting structured data requirements from product documentation.
+
+For each UI field, dashboard metric, filter, export column, or data-driven action mentioned in the document, produce a JSON entry with this shape:
+
+```json
+{
+  "field_label": "Human-readable label as shown in UI",
+  "field_key": "camelCase identifier",
+  "entity": "Which entity this belongs to (e.g. CustomerSummary)",
+  "data_type": "string | number | boolean | date | list | dict",
+  "null_semantics": "What NULL means (e.g. 'no revenue on record', 'not applicable')",
+  "formula": "Derivation rule if computed (else null)",
+  "grain": "Row level, aggregate, daily, monthly (if metric)",
+  "source_hint": "Any mention of where data comes from (table name, API, file)",
+  "priority": "must-have | nice-to-have | deferred",
+  "notes": "Any ambiguity, open questions, or conflicting statements"
+}
+```
+
+Rules:
+- Extract ONLY what is explicitly stated or clearly implied by the document.
+- Do not invent field requirements not mentioned.
+- If a formula is ambiguous, set `formula: null` and add a note.
+- If a field has multiple conflicting definitions, list all variants in `notes`.
+- Output a JSON array of requirement objects, followed by a short `## Gaps and Ambiguities` section listing unresolved questions.
+
+---
+
+DOCUMENT: