# Prompts Versioned Contract: Article Consolidation and Hygiene Runtime

**Feature Branch**: `006-article-consolidation-runtime`  
**Date**: 2026-08-23  
**Contract Version**: `1.0.0`  
**Status**: Complete  

---

## 1. Versioned Prompt Registry

The runtime manages exactly two atomic prompt contracts. Each prompt is versioned independently with an immutable semantic version and content hash.

| Prompt Identifier | File Path | Semantic Version | Input Context Structure | Expected Output Schema | Promptfoo Suite |
|:---|:---|:---|:---|:---|:---|
| `article_content_hygiene` | `prompts/article_content_hygiene.v1.txt` | `1.0.0` | 6-Block Context (`candidates-payload.schema.json`) | `hygiene-response.schema.json` | `evals/promptfoo.config.yaml` |
| `article_sentiment_tags` | `prompts/article_sentiment_tags.v1.txt` | `1.0.0` | 6-Block Context (Title, subtitle, sanitized Markdown body, language, minimal ECP identity: `qid`, `canonical_name`) | `enrichment-response.schema.json` | `evals/promptfoo.config.yaml` |

---

## 2. Normative 6-Block Prompt Ordering (Doc 07 §5.3)

Every prompt sent to the Model Gateway MUST strictly follow the exact 6-block sequence defined in the normative specification:

1. **Bloco 1: Regras do Sistema (System Role & Policy Constraints)**  
   Defines the agent/system persona, zero-hallucination mandate, and absolute prohibition of free-form text or Markdown invention.
2. **Bloco 2: Responsabilidade da Chamada (Task Responsibility)**  
   Declares the single, narrow responsibility of this specific logical invocation (candidate selection & micro-repair vs sentiment & tag extraction).
3. **Bloco 3: Schema e Enums (Output Schema & Enums)**  
   Provides the exact JSON schema and closed allowable categories/enums that the model MUST output.
4. **Bloco 4: Contexto Estrutural (Structural Document Context)**  
   Provides structural constraints, backbone extractor definition, metadata slots, and document language.
5. **Bloco 5: Candidatos e Evidências (Candidates & Evidence Payloads)**  
   Supplies the candidate blocks, links, images, and untrusted article content clearly delimited and separated from instructions (`<article_candidates>...</article_candidates>`).
6. **Bloco 6: Pedido Final de Resposta Estruturada (Final Structured Response Directive)**  
   Final closing directive commanding immediate output of the structured JSON response adhering strictly to the schema.

---

## 3. Strict Input Context Specifications

### 3.1 `article_content_hygiene` (FR-024, FR-058)
Receives strictly the normalized candidate payload (`candidates-payload.schema.json`) structured across the 6 blocks above. Article text is treated as untrusted data, enclosed in explicit boundary delimiters.

### 3.2 `article_sentiment_tags` (FR-037, FR-059)
Receives strictly the sanitized editorial context and minimal public ECP identity:
- Editorial Document: Final title, subtitle (if present), and intermediate sanitized Markdown body;
- Document Language;
- Target Entity Identity: strictly `qid` and `canonical_name` (zero ad-hoc keywords, zero description or aliases lists, zero raw ECP snapshot);
- Output JSON Schema (`enrichment-response.schema.json`).

---

## 4. Contractual Invariants

1. **Parity Guarantee**: The prompt files deployed in production runtime MUST be byte-for-byte identical (identical SHA-256 hash) to the prompt files evaluated by Promptfoo in `evals/`.
2. **Preflight Verification**: During startup and preflight, the runtime recalculates the SHA-256 hash of each prompt file and asserts equality against the approved release metadata (`src/core/release-metadata.json`). Any mismatch aborts execution with exit code `2`.
3. **Semantic Version Validation**: Semantic versions in prompt headers are parsed using standard semantic version parsers (`packaging.version` / pure tuple comparison), never regular expressions.
4. **Structured Invariants**:
   - Zero free-form body generation instructions.
   - Zero historical references or self-healing instructions.
   - All article text inputs explicitly delimited as untrusted data.
5. **Contract Testing**: `tests/contract/test_prompts_contract.py` validates prompt file existence, semver compliance via parser, SHA-256 calculation, schema associations, and byte parity with Promptfoo suites.