feat: split SRS into product requirements vs technical specs (srs-improved.md)

[paologaleotti]

What

Adds an editor step that runs in parallel with the final report and produces a derivative deliverable, srs-improved.md. Every [Work Item N] section is restructured into two subsections and enriched with the behaviors the reverse-diff found in code but missing from the SRS:

• Requisiti di prodotto — an authored, grounded product view: user need, feature goal, observable behavior/outcome and business rules.
• Specifiche tecniche — the faithful technical view: endpoints, events, db entities, validations, merge/migration ordering, implementation notes.

Output is markdown for manual import into a new Confluence page (Insert > Markup > Markdown) — the original page is never touched.

This PR also renames all workflow roles to English (cartographer, crawler, analyzer, verifier, reverse-scout, editor) and writes every prompt in English (deliverables stay Italian on purpose).

How — editor sub-pipeline

The editor is itself a small pipeline (runs concurrently with the report):

2 haiku readers (parallel)            sonnet               sonnet (read-only)        sonnet
  • SRS digest                ─┐
  • reverse-diff extract      ─┴──▶  converge  ──▶  adversarial verify  ──▶  one rework (on 'revise')
                                     writes srs-improved.md      falsifies it

• Two haiku readers do the cheap extraction (faithful per-WI technical content + product-intent sentences + verbatim product-context sections; reverse-diff behaviors with a spec-worthiness flag).
• Sonnet converge authors the document from both digests.
• Independent adversarial verifier (read-only) tries to falsify the result and returns objections in-band; on revise a single rework fixes the file. No separate review artifact.

Key behaviors

• Two derived views, asymmetric fidelity. The technical view is lossless/faithful (no technical fact dropped or invented); the product view may rephrase/condense but every claim must trace to the SRS (Overview / Vincoli / Assunzioni / UI-UX / WI intent). A purely-technical WI gets an explicit _(nessun requisito di prodotto dedicato: WI tecnico/abilitante)_ marker instead of padding.
• No code references in the document. File paths and line numbers are stripped (they churn over time); code snippets, event names, db entities/tables/columns and API endpoints are kept.
• Reverse-diff enrichment with a spec-worthiness filter. Contract / business-rule / error-semantics behaviors are merged into the relevant Work Item (phrased as requirements, not diff notes); incidental implementation details (internal status codes, in-memory optimizations, signer skips) go to a clearly-labeled ## Rilievi implementativi (non requisiti) appendix. Every added line carries a provenance marker _(da reverse-diff — presente nel codice, assente nell'SRS originale)_.
• Budget-gated skip-with-flag like the other optional roles; surfaced in RR-5.

Why

The SRS mixes product intent and implementation detail in the same paragraphs. Splitting them into a real product view vs a faithful technical view lets a PO validate behavior without parsing DDL, while the reverse-diff enrichment surfaces undocumented behavior the spec should capture. The independent adversarial verify keeps the rewrite honest (no dropped technical facts, no invented product claims, no code references, correctly-placed enrichment).

Validation

Test run against pagopa/interop-be-monorepo@develop (epic PIN-8621, SRS = "DRAFT SRS Link Template EService-Agevolata"), 10 analysis units:

• srs-improved.md regenerated with 0 code references, genuine product subsections, honest "nessun requisito" markers on technical-only WIs.
• Reverse-diff behaviors split into requirements vs the implementation-notes appendix; provenance-marked.
• Adversarial verifier caught and fixed real violations (leaked function names, API-contract prose in product sections) via a single rework — no review file produced.
• ~191k tokens, no budget cap hit.

[GorlemZ]

Review (no GitHub bias — posted on request). The editor sub-pipeline and role renames look solid: clean skeleton, correct null-handling in runEditor (skipEditor / reader / verify / rework failures), and the attached srs-improved.md shows it works end-to-end. Three points below — one design (token reserve), one docs, one prompt-contract.

Verdict: NEEDS_CHANGES (none are logic bugs in the skeleton).