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 114 existing placeholders (canonical: `PLACEHOLDER_MAP`)
- 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:
```python
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**
   ```python
   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

```bash
# 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

```bash
# 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:
```yaml
- 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)

```bash
# .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.