<!-- SPDX-License-Identifier: MIT -->
<!-- Copyright (c) PromptKit Contributors -->

---
name: requirements-reconciliation
type: reasoning
description: >
  Systematic protocol for reconciling multiple requirements documents
  from different sources (RFCs, implementations, specifications) into
  a unified requirements document. Aligns requirements across sources,
  classifies compatibility, and documents conflicts with resolution
  options for human decision-making.
applicable_to:
  - reconcile-requirements
---

# Protocol: Requirements Reconciliation

Apply this protocol when merging requirements extracted from multiple
sources — RFCs, implementations, specifications — into a single unified
requirements document. All sources are treated as equal inputs; no
source is inherently authoritative. The goal is to produce a "most
compatible" specification that documents what is universal, what is
majority practice, where sources diverge, and what is unique to a
single source.

## Phase 1: Source Inventory

Catalog the input requirements documents.

1. **For each source document**, record:
   - Source name and origin (e.g., "RFC 9293", "Linux TCP stack",
     "FreeBSD TCP stack", "Windows TCP stack")
   - Total requirement count
   - REQ-ID scheme used
   - Keyword strength distribution (count of MUST, SHOULD, MAY)
   - Categories/sections covered

2. **Assess coverage overlap**: Which functional areas do all sources
   cover? Which are covered by only a subset? Build a preliminary
   coverage matrix:

   | Functional Area | Source 1 | Source 2 | Source 3 | ... |
   |-----------------|----------|----------|----------|-----|
   | Connection setup | ✓ | ✓ | ✓ | |
   | Data transfer | ✓ | ✓ | ✓ | |
   | Congestion control | ✓ | ✓ | ○ | |

   Use ✓ for covered, ○ for partially covered, ✗ for absent.

## Phase 2: Requirement Alignment

Map requirements across sources to identify equivalences.

1. **For each requirement in each source**, find corresponding
   requirements in the other sources. Match by:
   - **Behavioral equivalence**: The requirements describe the same
     behavior, possibly in different words.
   - **Functional area + condition**: Requirements in the same
     functional area with the same triggering condition.
   - **State machine correspondence**: Requirements about the same
     state, transition, or event.

   Do NOT match by keyword or surface text similarity alone — two
   requirements can use similar words but specify different behaviors.

2. **Build an alignment table**: Each row represents a single behavior
   or constraint. Use temporary alignment IDs (U-001, U-002, ...) for
   working reference — these will be replaced with final unified
   REQ-IDs in Phase 5. Columns show how each source addresses it:

   | Alignment ID | Behavior | Source 1 | Source 2 | Source 3 | ... |
   |--------------|----------|----------|----------|----------|-----|
   | U-001 | SYN retransmit timeout | REQ-TCP-034-012 (MUST, 3s) | LINUX-CONN-007 (MUST, 1s) | BSD-CONN-004 (MUST, 3s) | |

3. **Flag unmatched requirements**: Requirements that exist in only
   one source and have no equivalent in any other source. These are
   candidates for the Extension compatibility class.

## Phase 3: Compatibility Classification

For each aligned behavior (each row in the alignment table):

1. **Compare keyword strength** across sources:
   - Do all sources agree on MUST/SHOULD/MAY?
   - Does one source say MUST while another says SHOULD?
   - Does any source omit this behavior entirely?

2. **Compare specified values** across sources:
   - Do all sources agree on thresholds, timeouts, sizes?
   - Where values differ, what is the range?

3. **Assign a compatibility class**:

   - **UNIVERSAL**: All sources specify this behavior with the same
     keyword strength and compatible values. This is safe to include
     as-is in the unified spec with the agreed keyword.

   - **MAJORITY**: Most sources (>50%) agree, but one or more diverge.
     Include in the unified spec with the majority keyword. Document
     which sources diverge and how.

   - **DIVERGENT**: Sources actively disagree — different keyword
     strengths, different values, or contradictory behaviors. Include
     in the unified spec with all variants documented. Do NOT pick a
     winner — the consumer must decide based on their use case.

   - **EXTENSION**: Only one source specifies this behavior. Include
     as MAY in the unified spec. Note which source defines it and
     why it may or may not be desirable for interoperability.

4. **Record the classification rationale**: For each non-UNIVERSAL
   requirement, briefly explain why it is not universal and what the
   specific differences are.

## Phase 4: Conflict Analysis

For DIVERGENT requirements, perform deeper analysis:

1. **Categorize the conflict**:
   - **Value disagreement**: Same behavior, different parameters
     (e.g., timeout 1s vs. 3s). Document the range across sources.
   - **Strength disagreement**: Same behavior, different keyword
     (e.g., MUST vs. SHOULD). May indicate different risk
     assessments.
   - **Behavioral disagreement**: Different behaviors for the same
     condition (e.g., "close connection" vs. "send reset"). These
     are true conflicts requiring human resolution.
   - **Presence disagreement**: One source requires behavior another
     explicitly prohibits. These are the most dangerous conflicts.

2. **Assess interoperability impact**: For each conflict, answer:
   - If an implementation follows source A's behavior and
     communicates with an implementation following source B's
     behavior, what happens?
   - Is the result a failure, a degraded experience, or transparent?

3. **Suggest resolution options** (but do NOT pick one):
   - Most conservative (strictest keyword, tightest value)
   - Most permissive (loosest keyword, widest value)
   - Most interoperable (the choice that causes fewest failures
     when communicating with other implementations)

## Phase 5: Unified Specification Assembly

Produce the unified requirements document.

1. **Assign unified REQ-IDs**: Use the tag and scheme provided by the
   template (e.g., `REQ-<TAG>-<CAT>-<NNN>` where `<TAG>` is the
   user-provided unified tag).

2. **For each unified requirement**, include:
   - The unified REQ-ID and requirement text
   - **Compatibility class**: UNIVERSAL / MAJORITY / DIVERGENT /
     EXTENSION
   - **Keyword strength**: The unified keyword (for UNIVERSAL and
     MAJORITY) or all source keywords (for DIVERGENT)
   - **Source mapping**: Which source requirements map to this
     unified requirement (REQ-IDs from each source)
   - **Acceptance criteria**: Derived from the source with the most
     specific criteria, or synthesized from multiple sources
   - **Divergence notes** (for non-UNIVERSAL): What differs and why

3. **Group by category**: Use functional area categories consistent
   across sources (e.g., CONNECTION, DATA_TRANSFER, CONGESTION,
   TEARDOWN, ERROR, SECURITY).

4. **Produce a reconciliation summary**:
   - Total unified requirements
   - Count by compatibility class
   - Count by keyword strength
   - List of DIVERGENT requirements requiring human resolution
   - List of EXTENSION requirements for review

## Phase 6: Interoperability Assessment

Produce an overall assessment of cross-source compatibility.

1. **Compatibility score**: % of requirements that are UNIVERSAL.
2. **Risk areas**: Functional areas with the highest concentration
   of DIVERGENT requirements.
3. **Interoperability hotspots**: Specific behaviors where
   implementations will conflict if they follow different sources.
4. **Recommendations**: Which DIVERGENT requirements are highest
   priority for resolution and why.

<!-- BEGIN ocserv extensions -->

## ocserv-Specific Extensions

The sections below extend the generic protocol for the sources and functional
areas most relevant to ocserv: OpenConnect protocol, Cisco AnyConnect client
behavior, relevant IETF RFCs, and the ocserv implementation itself.

### Phase 1 — Source Inventory (ocserv)

The standard sources for ocserv protocol reconciliation are:

| Source ID | Origin | Normative weight |
|-----------|--------|-----------------|
| `OC-PROTO` | OpenConnect protocol documentation and `libopenconnect` implementation | Primary interoperability target |
| `AC-CLIENT` | Observed Cisco AnyConnect client behavior (see `doc/README-cisco-svc.md`) | Must not break; divergence must be flagged |
| `RFC-TLS` | RFC 8446 (TLS 1.3) and RFC 5246 (TLS 1.2) | Normative for TLS channel |
| `RFC-DTLS` | RFC 9147 (DTLS 1.3) and RFC 6347 (DTLS 1.2) | Normative for DTLS data channel |
| `OCSERV` | ocserv implementation (`src/`) | Current behavior; may extend or diverge from specs |

When reconciling, read `doc/README-cisco-svc.md` before any other source —
it documents known AnyConnect deviations from the OpenConnect protocol that
ocserv already accommodates.

Functional areas for the coverage matrix:

| Functional Area | OC-PROTO | AC-CLIENT | RFC-TLS | RFC-DTLS | OCSERV |
|-----------------|----------|-----------|---------|----------|--------|
| TLS channel setup | | | | | |
| DTLS channel setup | | | | | |
| CSTP auth exchange | | | | | |
| Cookie / session resumption | | | | | |
| IP/route configuration push | | | | | |
| Keepalive / dead-peer detection | | | | | |
| Session teardown | | | | | |

### Phase 2 — Requirement Alignment (ocserv)

When matching across sources, use these alignment anchors:

- **CSTP header fields**: Match by header name (e.g., `X-CSTP-MTU`,
  `X-CSTP-DPD`). Differences in casing or allowed values are a DIVERGENT
  signal.
- **HTTP exchange sequence**: Match by phase (TLS handshake → HTTP GET/CONNECT
  → auth exchange → tunnel establishment). A requirement about "step N" in one
  source must be matched against the same protocol step, not the same HTTP
  method.
- **TLS/DTLS parameters**: Match by parameter class (cipher, version, extension).
  Different allowed ranges across sources are typically MAJORITY or DIVERGENT.
- **Timeout and keepalive values**: Match by semantic role (DPD interval,
  cookie lifetime, reconnect window). Numeric differences are DIVERGENT with
  value disagreement.

Flag unmatched `OCSERV` requirements as `[EXTENSION: ocserv-only]` — these
represent ocserv behaviors that extend the protocol (e.g., `occtl` management
interface, cgroup-based accounting, per-group config). They are not
interoperability risks but should be documented as extensions.

### Phase 3 — Compatibility Classification (ocserv)

Interpretation of compatibility classes in the ocserv context:

- **UNIVERSAL**: Safe to implement without concern for client or protocol
  compatibility. Core TLS handshake behavior, standard RFC MUST requirements.

- **MAJORITY**: Implement the majority behavior as the default. If `AC-CLIENT`
  is in the majority, the behavior is safe for AnyConnect compatibility.
  If `AC-CLIENT` is the diverging source, flag as `[COMPAT-RISK: AnyConnect]`.

- **DIVERGENT**: Do NOT silently pick one behavior. Present all variants to
  the maintainer. Behaviors where `AC-CLIENT` diverges from `OC-PROTO` or
  RFCs are the most common DIVERGENT class in ocserv and require explicit
  documentation in `doc/README-cisco-svc.md`.

- **EXTENSION**: Behaviors found only in `OCSERV`. These are ocserv-specific
  features (management socket, virtual hosting, per-group routing) or
  accommodations for specific client quirks. They carry no interoperability
  risk with standard clients but must be documented in `doc/ocserv.8.md`.

### Phase 4 — Conflict Analysis (ocserv)

For DIVERGENT requirements, apply this additional assessment:

- **AnyConnect breakage risk**: If an implementation following `OC-PROTO` or
  the RFC would break an AnyConnect client, the conflict is `[COMPAT-CRITICAL]`.
  These conflicts must be escalated to the maintainer before any code change.
- **OpenConnect client compatibility**: If a behavior would break the
  `openconnect` reference client used in tests (`tests/common.sh`), it is
  a test infrastructure risk in addition to a protocol risk.
- **Security downgrade risk**: Conflicts where one source requires a weaker
  TLS version, weaker cipher, or looser certificate validation must be
  classified as `[SEC-RISK]` regardless of which source is the majority.
  The most conservative (strictest) option is the only acceptable default.

Resolution option format for ocserv:
- **Most interoperable**: The choice that preserves both AnyConnect and
  OpenConnect client compatibility.
- **Most RFC-compliant**: The choice that strictly follows the IETF RFC.
- **Current ocserv behavior**: What `OCSERV` currently does (baseline).

### Phase 5 — Unified Specification Assembly (ocserv)

Use these category tags in unified REQ-IDs:

| Tag | Description |
|-----|-------------|
| `CONN` | TLS/DTLS connection establishment |
| `AUTH` | Authentication exchange (CSTP auth headers, certificate validation) |
| `SESSION` | Cookie issuance, session resumption, roaming |
| `DATA` | Data channel (CSTP, DTLS packet framing, MTU, compression) |
| `CTRL` | Keepalive, DPD, disconnect signaling |
| `CFG` | IP/route/DNS configuration push to client |
| `COMPAT` | AnyConnect-specific behaviors that deviate from OC-PROTO |
| `SEC` | Security properties (cipher requirements, certificate validation) |
| `EXT` | ocserv extensions not present in OC-PROTO or client behavior |

For every `COMPAT` requirement, add a note referencing `doc/README-cisco-svc.md`
if the behavior is already documented there, or flag it for addition if not.

<!-- END ocserv extensions -->
