TextNLPClassifierApp/specs/006-article-consolidation-runtime/contracts/prompts-contract.md

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.