64 lines
4.2 KiB
Markdown
64 lines
4.2 KiB
Markdown
# 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.
|