[EPIC][expert] Requirement / SPEC expert: normalize obligations, freeze intent, and block silent requirement drift #420

New issue

Open

opened 2026-09-08 01:29:22 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 01:29:22 +00:00

Owner

Parent: #376
Depends on: #377
Integrates with: #93, existing rlm_spec* APIs, #56

Goal

Add a reusable Requirement / SPEC Expert responsible for turning an operator requirement or existing structured requirement set into a validated, inspectable, immutable Frozen Spec suitable for the expert loop.

This expert does not plan implementation and does not execute project mutations. It establishes what must be true.

Primary responsibilities

normalize structured requirement input into the canonical SPEC language;
resolve explicit aliases/known schema forms deterministically;
detect malformed, contradictory, underspecified or mutually incompatible obligations;
attach requirement provenance;
validate exact requirement structure and invariants;
freeze accepted requirements using the existing immutable SPEC/version contract;
expose unanswered/ambiguous requirement questions structurally;
compare proposed later changes against the Frozen Spec and reject silent weakening.

Natural-language input

Natural language is an optional front door, not the authority boundary.

Preferred order:

structured/typed input
  -> deterministic normalization
  -> existing SPEC validation/freeze

NL input
  -> deterministic parsers/templates/known vocabulary where sufficient
  -> explicit ambiguity if not sufficient
  -> optional LLM normalization fallback if enabled
  -> validate normalized data
  -> freeze

Any LLM use is an explicit metered fallback. Model output is inert candidate SPEC data until the canonical SPEC validator accepts it.

Expert contract

Conceptual accepted goals:

normalize_requirement(Input).
validate_requirement(SpecCandidate).
freeze_requirement(SpecCandidate).
requirement_gap(FrozenOrCandidate).
compare_requirement_change(FrozenSpec, CandidateChange).

Outputs preserve at least:

normalized requirements
validation diagnostics
ambiguities / contradictions
provenance
Frozen Spec reference + fingerprint when accepted
explicit unknown/blocked status when not accepted

Hard invariant: Frozen Spec is not repairable

Downstream Planner, Write, Repair, Review and Verify experts may inspect the Frozen Spec but cannot mutate it in place.

If the operator genuinely changes requirements, create a new version/superseding Spec through this expert and preserve the relationship between versions.

A repair loop is forbidden from deleting or weakening an obligation merely because it is hard to satisfy.

Deterministic reasoning

Use Prolog rules/constraints where useful for:

duplicate/equivalent obligations;
incompatible constraints;
required field/schema checks;
implication/redundancy relations;
closed enumerations;
simple numeric/range constraints;
dependency/order constraints;
domain-independent consistency rules.

Consider CLP(FD)/CLP(Q/R) where applicable rather than asking a model to reason about formal constraints.

Integration

The full expert loop starts only after either:

ok(FrozenSpec)

or an explicitly supplied existing valid Frozen Spec.

The Coordinator Expert receives the fingerprinted Frozen Spec and must bind all planning/replanning against it.

The Verify Expert evaluates that same immutable ref.

Acceptance

Structured requirements compile/freeze with zero model calls.
Equivalent duplicate requirements normalize deterministically.
Contradictory constraints return structured contradiction evidence rather than an arbitrary winner.
Missing required information remains unknown/blocked.
Optional NL fallback is separately traced/metered and its output must pass canonical validation.
Model output cannot smuggle capability/authority into the SPEC.
Once frozen, downstream repair/replan attempts cannot mutate or drop obligations.
Operator-authorized requirement change creates a new SPEC version with provenance.
SPEC fingerprint used by Planner and Verify is stable and inspectable.

Non-goals

No project mutation.
No execution planning beyond requirement dependencies needed for validation.
No acceptance of model prose as verified requirement state.

Refs #376 #377 #93 #56

Parent: #376 Depends on: #377 Integrates with: #93, existing `rlm_spec*` APIs, #56 ## Goal Add a reusable **Requirement / SPEC Expert** responsible for turning an operator requirement or existing structured requirement set into a validated, inspectable, immutable Frozen Spec suitable for the expert loop. This expert does **not** plan implementation and does not execute project mutations. It establishes what must be true. ## Primary responsibilities - normalize structured requirement input into the canonical SPEC language; - resolve explicit aliases/known schema forms deterministically; - detect malformed, contradictory, underspecified or mutually incompatible obligations; - attach requirement provenance; - validate exact requirement structure and invariants; - freeze accepted requirements using the existing immutable SPEC/version contract; - expose unanswered/ambiguous requirement questions structurally; - compare proposed later changes against the Frozen Spec and reject silent weakening. ## Natural-language input Natural language is an optional front door, not the authority boundary. Preferred order: ```text structured/typed input -> deterministic normalization -> existing SPEC validation/freeze NL input -> deterministic parsers/templates/known vocabulary where sufficient -> explicit ambiguity if not sufficient -> optional LLM normalization fallback if enabled -> validate normalized data -> freeze ``` Any LLM use is an explicit metered fallback. Model output is inert candidate SPEC data until the canonical SPEC validator accepts it. ## Expert contract Conceptual accepted goals: ```prolog normalize_requirement(Input). validate_requirement(SpecCandidate). freeze_requirement(SpecCandidate). requirement_gap(FrozenOrCandidate). compare_requirement_change(FrozenSpec, CandidateChange). ``` Outputs preserve at least: ```text normalized requirements validation diagnostics ambiguities / contradictions provenance Frozen Spec reference + fingerprint when accepted explicit unknown/blocked status when not accepted ``` ## Hard invariant: Frozen Spec is not repairable Downstream Planner, Write, Repair, Review and Verify experts may inspect the Frozen Spec but cannot mutate it in place. If the operator genuinely changes requirements, create a new version/superseding Spec through this expert and preserve the relationship between versions. A repair loop is forbidden from deleting or weakening an obligation merely because it is hard to satisfy. ## Deterministic reasoning Use Prolog rules/constraints where useful for: - duplicate/equivalent obligations; - incompatible constraints; - required field/schema checks; - implication/redundancy relations; - closed enumerations; - simple numeric/range constraints; - dependency/order constraints; - domain-independent consistency rules. Consider CLP(FD)/CLP(Q/R) where applicable rather than asking a model to reason about formal constraints. ## Integration The full expert loop starts only after either: ```text ok(FrozenSpec) ``` or an explicitly supplied existing valid Frozen Spec. The Coordinator Expert receives the fingerprinted Frozen Spec and must bind all planning/replanning against it. The Verify Expert evaluates that same immutable ref. ## Acceptance - [ ] Structured requirements compile/freeze with zero model calls. - [ ] Equivalent duplicate requirements normalize deterministically. - [ ] Contradictory constraints return structured contradiction evidence rather than an arbitrary winner. - [ ] Missing required information remains unknown/blocked. - [ ] Optional NL fallback is separately traced/metered and its output must pass canonical validation. - [ ] Model output cannot smuggle capability/authority into the SPEC. - [ ] Once frozen, downstream repair/replan attempts cannot mutate or drop obligations. - [ ] Operator-authorized requirement change creates a new SPEC version with provenance. - [ ] SPEC fingerprint used by Planner and Verify is stable and inspectable. ## Non-goals - No project mutation. - No execution planning beyond requirement dependencies needed for validation. - No acceptance of model prose as verified requirement state. Refs #376 #377 #93 #56