mitai-jinkendo/docs/PLACEHOLDER_GOVERNANCE.md

Placeholder Governance Guidelines

Version: 1.0.0 Status: Normative (Mandatory) Effective Date: 2026-03-29 Applies To: All existing and future placeholders

---

1. Purpose

This document establishes mandatory governance rules for placeholder management in the Mitai Jinkendo system. All placeholders must comply with the normative standard defined in PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md.

Key Principle: Placeholders are API contracts, not loose prompt helpers.

---

2. Scope

These guidelines apply to:

• All 116 existing placeholders
• All new placeholders
• All modifications to existing placeholders
• All placeholder deprecations
• All placeholder documentation

---

3. Mandatory Requirements for New Placeholders

3.1 Before Implementation

Before implementing a new placeholder, you MUST:

1. Define Complete Metadata

   • All fields from PlaceholderMetadata dataclass must be specified
   • No unknown, null, or empty required fields
   • Semantic contract must be precise and unambiguous

2. Choose Correct Type

   • atomic - Single atomic value (e.g., weight, age)
   • raw_data - Structured data (JSON, lists)
   • interpreted - AI-interpreted or derived values
   • NOT legacy_unknown (only for existing legacy placeholders)

3. Specify Time Window

   • latest, 7d, 14d, 28d, 30d, 90d, custom, mixed
   • NOT unknown
   • Document in semantic_contract if variable

4. Document Data Source

   • Resolver function name
   • Data layer module (if applicable)
   • Source database tables
   • Dependencies

3.2 Naming Conventions

Placeholder keys must follow these patterns:

Good:

• weight_7d_median - Clear time window
• protein_adequacy_28d - Clear semantic meaning
• correlation_energy_weight_lag - Clear relationship

Bad:

• weight_trend - Ambiguous time window (7d? 28d? 90d?)
• activity_summary - Ambiguous scope
• data_summary - Too generic

Rules:

• Include time window suffix if applicable (_7d, _28d, etc.)
• Use descriptive names, not abbreviations
• Lowercase with underscores (snake_case)
• No German umlauts in keys

3.3 Implementation Checklist

Before merging code with a new placeholder:

• Metadata defined in placeholder_metadata_complete.py
• Added to PLACEHOLDER_MAP in placeholder_resolver.py
• Added to catalog in get_placeholder_catalog()
• Resolver function implemented
• Data layer function implemented (if needed)
• Tests written
• Validation passes
• Documentation updated

---

4. Modifying Existing Placeholders

4.1 Non-Breaking Changes (Allowed)

You may make these changes without breaking compatibility:

• Adding fields to metadata (e.g., notes, known_issues)
• Improving semantic_contract description
• Adding confidence_logic
• Adding quality_filter_policy
• Resolving unknown fields to concrete values

4.2 Breaking Changes (Requires Deprecation)

These changes REQUIRE deprecation path:

• Changing time window (e.g., 7d → 28d)
• Changing output type (e.g., string → number)
• Changing semantic meaning
• Changing unit
• Changing data source

Process:

1. Mark original placeholder as deprecated: true
2. Set replacement: "{{new_placeholder_name}}"
3. Create new placeholder with corrected metadata
4. Document in known_issues
5. Update all prompts/pipelines to use new placeholder
6. Remove deprecated placeholder after 2 version cycles

4.3 Forbidden Changes

You MUST NOT:

• Silent breaking changes (change semantics without deprecation)
• Remove placeholders without deprecation path
• Change placeholder key/name (always create new)

---

5. Quality Standards

5.1 Semantic Contract Requirements

Every placeholder's semantic_contract must answer:

1. What does it represent?
2. How is it calculated?
3. What time window applies?
4. What data sources are used?
5. What happens when data is missing?

Example (Good):

"Letzter verfügbarer Gewichtseintrag aus weight_log, keine Mittelung
oder Glättung. Confidence = 'high' if data exists, else 'insufficient'.
Returns formatted string '85.8 kg' or 'nicht verfügbar'."

Example (Bad):

"Aktuelles Gewicht"  // Too vague

5.2 Confidence Logic

Placeholders using data_layer functions SHOULD document confidence logic:

• When is data considered high, medium, low, insufficient?
• What are the minimum data point requirements?
• How are edge cases handled?

5.3 Error Handling

All placeholders must define error handling policy:

• Default: Return "nicht verfügbar" string
• Never throw exceptions into prompt layer
• Document in exception_handling field

---

6. Validation & Testing

6.1 Automated Validation

All placeholders must pass:

from placeholder_metadata import validate_metadata

violations = validate_metadata(placeholder_metadata)
errors = [v for v in violations if v.severity == "error"]
assert len(errors) == 0, "Validation failed"

6.2 Manual Review

Before merging, reviewer must verify:

• Metadata is complete and accurate
• Semantic contract is precise
• Time window is explicit
• Data source is documented
• Tests are written

---

7. Documentation Requirements

7.1 Catalog Updates

When adding/modifying placeholders:

1. Update placeholder_metadata_complete.py
2. Regenerate catalog: python backend/generate_placeholder_catalog.py
3. Commit generated files:
   • PLACEHOLDER_CATALOG_EXTENDED.json
   • PLACEHOLDER_CATALOG_EXTENDED.md
   • PLACEHOLDER_GAP_REPORT.md

7.2 Usage Tracking

Document where placeholder is used:

• Prompt names/IDs in used_by.prompts
• Pipeline names in used_by.pipelines
• Chart endpoints in used_by.charts

---

8. Deprecation Process

8.1 When to Deprecate

Deprecate a placeholder if:

• Semantics are incorrect or ambiguous
• Time window is unclear
• Better alternative exists
• Data source changed fundamentally

8.2 Deprecation Steps

1. Mark as Deprecated

   deprecated=True,
   replacement="{{new_placeholder_name}}",
   known_issues=["Deprecated: <reason>"]
   

2. Create Replacement

   • Implement new placeholder with correct metadata
   • Add to catalog
   • Update tests

3. Update Consumers

   • Find all prompts using old placeholder
   • Update to use new placeholder
   • Test thoroughly

4. Grace Period

   • Keep deprecated placeholder for 2 version cycles (≥ 2 months)
   • Display deprecation warnings in logs

5. Removal

   • After grace period, remove from PLACEHOLDER_MAP
   • Keep metadata entry marked as deprecated: true for history

---

9. Review Checklist

Use this checklist for code reviews involving placeholders:

New Placeholder:

• All metadata fields complete
• Type is not legacy_unknown
• Time window is not unknown
• Output type is not unknown
• Semantic contract is precise
• Data source documented
• Resolver implemented
• Tests written
• Catalog updated
• Validation passes

Modified Placeholder:

• Changes are non-breaking OR deprecation path exists
• Metadata updated
• Tests updated
• Catalog regenerated
• Affected prompts/pipelines identified

Deprecated Placeholder:

• Marked as deprecated
• Replacement specified
• Consumers updated
• Grace period defined

---

10. Tooling

10.1 Metadata Validation

# Validate all metadata
python backend/generate_complete_metadata.py

# Generate catalog
python backend/generate_placeholder_catalog.py

# Run tests
pytest backend/tests/test_placeholder_metadata.py

10.2 Export Endpoints

# Legacy export (backward compatible)
GET /api/prompts/placeholders/export-values

# Extended export (with complete metadata)
GET /api/prompts/placeholders/export-values-extended

---

11. Enforcement

11.1 CI/CD Integration (Recommended)

Add to CI pipeline:

- name: Validate Placeholder Metadata
  run: |
    python backend/generate_complete_metadata.py
    if [ $? -ne 0 ]; then
      echo "Placeholder metadata validation failed"
      exit 1
    fi    

11.2 Pre-commit Hook (Optional)

# .git/hooks/pre-commit
python backend/generate_complete_metadata.py
if [ $? -ne 0 ]; then
  echo "Placeholder metadata validation failed. Fix issues before committing."
  exit 1
fi

---

12. Contacts & Questions

• Normative Standard: PLACEHOLDER_METADATA_REQUIREMENTS_V2_NORMATIVE.md
• Implementation: backend/placeholder_metadata.py
• Registry: backend/placeholder_metadata_complete.py
• Catalog Generator: backend/generate_placeholder_catalog.py
• Tests: backend/tests/test_placeholder_metadata.py

For questions or clarifications, refer to the normative standard first.

---

13. Version History

Version	Date	Changes
1.0.0	2026-03-29	Initial governance guidelines

---

Remember: Placeholders are API contracts. Treat them with the same care as public APIs.