feat(runtime): implement single-article consolidation runtime and modularize codebase
This commit is contained in:
@@ -0,0 +1,129 @@
|
||||
# Requirements Readiness Checklist: Article Consolidation and Hygiene Runtime
|
||||
|
||||
**Purpose**: Formal requirements-quality review and readiness checklist covering functional completeness, architectural constraints, security invariants, operational resilience, and contractual consistency across the runtime specification (FR-001 to FR-084).
|
||||
**Created**: 2026-08-23
|
||||
**Feature**: [`spec.md`](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/006-article-consolidation-runtime/spec.md)
|
||||
|
||||
**Review Ownership**: This checklist is a reviewer-owned requirements-quality review artifact. Mark an item `[x]` only when the reviewer determines the requirements-quality criterion is satisfied.
|
||||
**Marker Semantics**: `[x]` means the criterion has been reviewed and satisfied for requirements quality. It does not mean implementation work is complete.
|
||||
|
||||
---
|
||||
|
||||
## 1. Requirement Completeness
|
||||
|
||||
- [x] CHK001 Are extraction payload ingestion and field retention requirements specified for all three supported extractors (`trafilatura`, `newspaper4k`, `readability`)? [Completeness, Spec §FR-010, §FR-011]
|
||||
- [x] CHK002 Are structural preservation requirements explicitly defined for all candidate element types (paragraphs, headings, lists, quotes, links, images)? [Completeness, Spec §FR-014, §FR-030]
|
||||
- [x] CHK003 Are the 10 sequential validation steps of the hygiene harness fully enumerated and ordered in the specification? [Completeness, Spec §FR-024, §FR-025]
|
||||
- [x] CHK004 Are the 5 allowable text micro-repair categories exhaustively defined with explicit acceptance/rejection criteria? [Completeness, Spec §FR-027, §FR-028]
|
||||
- [x] CHK005 Are requirements for ECP relevance classification handling defined for all 4 decision categories (`DIRECT_INHERENT`, `CONTEXTUAL_INHERENT`, `TANGENTIAL`, `NOT_RELATED`)? [Completeness, Spec §FR-031, §FR-033, §FR-034]
|
||||
- [x] CHK006 Are sentiment classification and native language tag enrichment requirements documented with strict input/output bounds? [Completeness, Spec §FR-037, §FR-038, §FR-039, §FR-040]
|
||||
- [x] CHK007 Are state machine lifecycle transitions and persistence requirements defined for all valid paths from `received` to terminal states? [Completeness, Spec §FR-046, §FR-050]
|
||||
- [x] CHK008 Are all 9 versioned contract schemas identified and cross-referenced with explicit versioning rules? [Completeness, Spec §FR-004]
|
||||
|
||||
---
|
||||
|
||||
## 2. Requirement Clarity & Precision
|
||||
|
||||
- [x] CHK009 Is the input size threshold quantified with an exact byte limit and unambiguous pre-provider failure behavior? [Clarity, Spec §FR-056]
|
||||
- [x] CHK010 Is the definition of "sensitive entities" in text micro-repairs unambiguously clarified to prevent ungrounded modifications to names, dates, numbers, and facts? [Clarity, Spec §FR-027, §FR-028, §FR-029]
|
||||
- [x] CHK011 Are the minimal ECP identity fields supplied to the enrichment prompt strictly limited to `qid` and `canonical_name` without vague contextual keyword lists? [Clarity, Spec §FR-037, §FR-059]
|
||||
- [x] CHK012 Is the candidate equivalence mapping defined explicitly as non-destructive evidence rather than automatic deduplication? [Clarity, Spec §FR-014, §FR-020]
|
||||
- [x] CHK013 Is the zero-regex policy quantified with unambiguous static AST, JSON schema, and Promptfoo evaluation constraints? [Clarity, Spec §FR-015, §FR-070]
|
||||
- [x] CHK014 Are the exit codes of the CLI interface explicitly mapped to specific execution outcomes without ambiguity between article validation and configuration errors? [Clarity, Spec §FR-003, §FR-047]
|
||||
|
||||
---
|
||||
|
||||
## 3. Requirement Consistency & Alignment
|
||||
|
||||
- [x] CHK015 Do state transition definitions align consistently between textual requirements and formal data model entity specifications? [Consistency, Spec §FR-046]
|
||||
- [x] CHK016 Are the error codes in the output manifest strictly consistent with the normative 16-code error catalog? [Consistency, Spec §FR-047]
|
||||
- [x] CHK017 Is the terminal state `ecp_rejected` consistently specified as producing an output manifest with `generate_markdown: false` and exactly zero Markdown files? [Consistency, Spec §FR-034, §FR-046, §FR-050]
|
||||
- [x] CHK018 Do the prompt context specifications in §FR-024 and §FR-037 align with the 6-block prompt architecture defined in the harness specification? [Consistency, Spec §FR-058, §FR-059]
|
||||
- [x] CHK019 Are the decoupling requirements between semantic schema invalidity (fallback trigger) and grounding violations (immediate invalidation) consistently preserved across all hygiene requirements? [Consistency, Spec §FR-026, §US2]
|
||||
|
||||
---
|
||||
|
||||
## 4. Acceptance Criteria & Measurability
|
||||
|
||||
- [x] CHK020 Are all 11 release invariants defined with measurable zero-tolerance thresholds (count = 0)? [Measurability, Spec §FR-075]
|
||||
- [x] CHK021 Can the prompt parity invariant between runtime production prompts and Promptfoo test suites be objectively verified by SHA-256 byte comparison? [Measurability, Spec §FR-057, §FR-077]
|
||||
- [x] CHK022 Are staging performance and latency SLOs formulated as measurable empirical calibration gates prior to production release? [Measurability, Spec §FR-076]
|
||||
- [x] CHK023 Can the batch wrapper rejection rule (`"articles": false`) be objectively evaluated against any composite JSON payload? [Measurability, Spec §FR-003, §FR-007, Contract 1]
|
||||
- [x] CHK024 Is the holdout dataset evaluation criterion objectively separated from prompt few-shot development data? [Measurability, Spec §FR-073]
|
||||
|
||||
---
|
||||
|
||||
## 5. Scenario & Flow Coverage
|
||||
|
||||
- [x] CHK025 Are requirements defined for the primary happy path of direct inherence resulting in published Markdown and manifest? [Coverage, Spec §US1, §FR-031, §FR-033, §FR-037, §FR-038, §FR-039, §FR-040, §FR-047, §FR-048, §FR-049, §FR-050]
|
||||
- [x] CHK026 Are requirements defined for alternate flows involving primary model failure and automated fallback to the secondary provider? [Coverage, Spec §US6, §FR-043, §FR-044, §FR-045]
|
||||
- [x] CHK027 Are requirements defined for exception flows involving unparseable JSON inputs, missing extractors, and schema violations? [Coverage, Spec §US2, §FR-005, §FR-006, §FR-007, §FR-047]
|
||||
- [x] CHK028 Are requirements defined for recovery flows involving interrupted writes and process crash reconciliation? [Coverage, Spec §US8, §FR-009, §FR-050, §FR-081]
|
||||
- [x] CHK029 Are requirements defined for idempotency replay when identical fingerprints are submitted concurrently or sequentially? [Coverage, Spec §US3, §FR-009]
|
||||
|
||||
---
|
||||
|
||||
## 6. Edge Case & Boundary Coverage
|
||||
|
||||
- [x] CHK030 Are requirements specified for handling articles with empty body text, missing titles, or missing source URLs? [Edge Case, Spec §FR-007]
|
||||
- [x] CHK031 Are boundary conditions specified for documents exceeding maximum allowed input byte limits? [Edge Case, Spec §FR-056]
|
||||
- [x] CHK032 Are requirements specified for limited technical retries on timeout, connection interruption/reset, HTTP 429 with backoff up to the configured limit, HTTP 5xx, and empty technical responses? [Edge Case, Spec §FR-043]
|
||||
- [x] CHK033 Are boundary constraints defined for the minimum (3) and maximum (8) allowable tags in enrichment responses? [Edge Case, Spec §FR-038]
|
||||
- [x] CHK034 Is the behavior specified for corrupted Unicode or mojibake in proper names versus factual semantic edits? [Edge Case, Spec §FR-029]
|
||||
|
||||
---
|
||||
|
||||
## 7. Non-Functional & Security Requirements (SEC-001 to SEC-008)
|
||||
|
||||
- [x] CHK035 Are prompt injection resistance requirements specified to prevent instructions within article bodies from overriding system directives (SEC-001)? [Security, Spec §FR-051, §FR-058, §FR-059, §FR-071]
|
||||
- [x] CHK036 Are credential and secret redaction requirements defined for technical stderr logs, trace attributes, and manifests (SEC-002)? [Security, Spec §FR-055, §FR-063, §FR-071]
|
||||
- [x] CHK037 Are filesystem path traversal prevention requirements documented for article paths and output filenames (SEC-003)? [Security, Spec §FR-053, §FR-054, §FR-071]
|
||||
- [x] CHK038 Are requirements defined to prevent local filesystem exhaustion and unbounded temporary file accumulation (SEC-004)? [Security, Spec §FR-050, §FR-056, §FR-078, §FR-081, §FR-082]
|
||||
- [x] CHK039 Are untrusted input size limits specified to prevent denial-of-service via large payloads (SEC-005)? [Security, Spec §FR-056, §FR-071]
|
||||
- [x] CHK040 Are requirements defined to prevent schema poisoning and local duplicate validation definitions (SEC-006)? [Security, Spec §FR-002, §FR-005, §FR-071]
|
||||
- [x] CHK041 Are requirements specified for handling SQLite lock contention and database lock timeouts (SEC-007)? [Security, Spec §FR-009, §FR-046, §FR-071]
|
||||
- [x] CHK042 Are requirements defined for secure telemetry degradation when observability endpoints are unreachable (SEC-008)? [Security, Spec §FR-064, §FR-071]
|
||||
|
||||
---
|
||||
|
||||
## 8. Operational Resilience & Lifecycle Governance (FR-081, FR-084)
|
||||
|
||||
- [x] CHK043 Are consistent database backup and restore requirements documented using native SQLite APIs without distributed database dependencies? [Resilience, Spec §FR-081]
|
||||
- [x] CHK044 Are graceful shutdown requirements defined for `SIGTERM` and `SIGINT` signals to flush in-flight telemetry and prevent SQLite state corruption? [Resilience, Spec §FR-081]
|
||||
- [x] CHK045 Are credential rotation and certified model rotation procedures testable and verifiable via preflight configuration checks? [Resilience, Spec §FR-081, §FR-083]
|
||||
- [x] CHK046 Are rollback procedures specified for reverting releases while preserving offline telemetry and historical state? [Resilience, Spec §FR-081]
|
||||
- [x] CHK047 Is the multi-stakeholder responsibility matrix (Orchestrator, Operations, Engineering, Curator/Eval) unambiguously mapped without overlapping operational boundaries? [Governance, Spec §US9, §FR-084]
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies & Contract Traceability
|
||||
|
||||
- [x] CHK048 Are all runtime dependencies evaluated against the 7 mandatory criteria: requirement served, standard-library alternative, security impact, maintenance impact, license, size impact, and startup impact? [Governance, Spec §FR-002]
|
||||
- [x] CHK049 Is the local canonical ECP schema resolution specified via `referencing.Registry` without network HTTP lookups? [Governance, Spec §FR-002, §FR-005]
|
||||
- [x] CHK050 Is the release metadata artifact (`src/core/release-metadata.json`) specified as the immutable verification source for config hashes, prompt hashes, and model certifications? [Governance, Spec §FR-042, §FR-077, §FR-078]
|
||||
|
||||
---
|
||||
|
||||
## 10. Scope Boundaries, Quality Gates & Operations (FR-001 to FR-084)
|
||||
|
||||
- [x] CHK051 Are the master simplicity constraints explicitly reviewable, including minimum necessary code, no anticipatory self-healing, no API, no internal batch or worker pools, and no LangChain, LangGraph, agents, planners, workflow frameworks, Postgres, external queues, or object storage inside the runtime? [Scope, Spec §FR-001, §FR-002, §FR-003, §FR-046]
|
||||
- [x] CHK052 Are requirements explicit that the ECP snapshot is mandatory, selected_extractor is never recalculated or substituted, unknown input fields are preserved, and all terminating local validations occur before any remote call? [Completeness, Spec §FR-005, §FR-006, §FR-007, §FR-010, §FR-011, §FR-012]
|
||||
- [x] CHK053 Are fingerprint composition, functional configuration inclusion, operational secret exclusion, and reproducible packaging requirements completely and unambiguously defined? [Precision, Spec §FR-008, §FR-013]
|
||||
- [x] CHK054 Are deterministic URL, publication date, title, subtitle, and author resolution rules fully specified, including priority orders, omission behavior, and the prohibition on splitting author strings by delimiters? [Completeness, Spec §FR-017, §FR-018, §FR-019]
|
||||
- [x] CHK055 Is mandatory LLM hygiene required even under complete extractor consensus, with output limited to candidate IDs and repair diffs and with all editorial preservation rules explicitly defined? [Completeness, Spec §FR-022, §FR-023, §FR-024, §FR-030]
|
||||
- [x] CHK056 Are the exact manifest, conditional Markdown, YAML front matter, canonical body rendering, hashing, atomic persistence, SQLite consistency, and reconciliation requirements completely specified? [Completeness, Spec §FR-047, §FR-048, §FR-049, §FR-050]
|
||||
- [x] CHK057 Are Langfuse spans, per-attempt generations, trace-content policy, redaction, pending telemetry, structured logs, metric cardinality, normative metrics, dashboards, and non-executing prompt review signals completely specified? [Observability, Spec §FR-060 to §FR-069]
|
||||
- [x] CHK058 Are Promptfoo change triggers, 20-case regression, golden-set ground truth, holdout isolation, 10 fault-injection scenarios, per-slice quality gates, 11 zero-tolerance invariants, load test, and release evidence requirements all objectively verifiable? [Quality Gates, Spec §FR-070 to §FR-077]
|
||||
- [x] CHK059 Are preflight, smoke test, 11-step deployment, retention, reconciliation, orphan cleanup, rotations, incident response, reprocessing rules, and prohibitions on manual production artifact editing completely specified? [Operations, Spec §FR-078 to §FR-084]
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Mark items `[x]` only after review confirms the requirement-quality criterion is satisfied
|
||||
- Leave items unchecked when they still require clarification, correction, or reviewer evaluation
|
||||
- `/speckit-implement` reads checklist checkbox state as a gate and must not modify markers
|
||||
- `checklists/requirements.md` has a separate built-in lifecycle maintained by `/speckit-specify` and `/speckit-clarify`
|
||||
- Add comments or findings inline
|
||||
- Link to relevant resources or documentation
|
||||
- Items are numbered sequentially (CHK001 to CHK059) for easy reference
|
||||
@@ -0,0 +1,54 @@
|
||||
# Specification Quality Checklist: Article Consolidation and Hygiene Runtime
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-08-23
|
||||
**Feature**: [spec.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/006-article-consolidation-runtime/spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Verification Notes for the 4 Precision Adjustments
|
||||
|
||||
1. **FR-057 Assertions do Promptfoo Completas (Doc 04 §22.2 e Doc 07 §11.3)**:
|
||||
- JSON Schema validation
|
||||
- Validadores Python customizados sem regex
|
||||
- IDs pertencentes ao contexto
|
||||
- Conjuntos e ordem esperada
|
||||
- URLs pertencentes à entrada
|
||||
- Precisão e recall
|
||||
- Enum e cardinalidade
|
||||
- Diffs com bibliotecas de sequência/Unicode sem regex
|
||||
- Comparação com a verdade de referência
|
||||
- Métricas de custo e latência
|
||||
2. **FR-073 Contrato das Tags na Golden Set**:
|
||||
- Atualizado para `accepted tags or a closed evaluation rubric`.
|
||||
3. **US9 (Cenário 4) e FR-084 / Runbook Matriz de Responsabilidades Exata**:
|
||||
- *Orchestrator*: provide article/ECP, control concurrency, and consume the manifest.
|
||||
- *Operations*: deploy, monitor, recover, and execute rollback.
|
||||
- *Engineering*: correct code, prompts, schemas, or integrations through the normal release process.
|
||||
- *Curator/Eval*: maintain the golden set and approve quality.
|
||||
4. **US2 Cenário 4 e FR-026 Desacoplamento entre Schema Inválido e Grounding Violation**:
|
||||
- `GROUNDING_VIOLATION` restrito a IDs, URLs, imagens ou conteúdo sem origem nos candidatos de entrada (invalida toda a resposta e aciona fallback).
|
||||
- Schema inválido tratado como falha semântica acionando fallback; esgotadas as opções de fallback, aplica-se `HYGIENE_FAILED`.
|
||||
Reference in New Issue
Block a user