# 0.5.5 Release Spec

## Purpose

This document is the release-level specification for the `0.5.5` stabilization
release of `nginx-markdown-for-agents`. It establishes the release framing,
shared principles, routing model, verification policy, harness review policy,
change control rules, and acceptance model that govern the complete `0.5.5`
stabilization workstreams.

This document does not define implementation details, per-file code paths, or
subsystem-specific acceptance criteria — those belong to the individual
workstream specs (the stabilization workstreams).

## Glossary

- **Release_Spec**: This document, the release-level specification
  that frames and governs the `0.5.5` spec set.
- **Sub_Spec**: One of the six workstream specifications that
  address a specific correctness or quality surface within the release.
- **Harness**: The repo-owned verification and routing infrastructure defined by
  `AGENTS.md`, `docs/harness/README.md`, `docs/harness/core.md`,
  `docs/harness/routing-manifest.json`, `docs/harness/routing-manifest.md`, and
  `docs/harness/risk-packs/README.md`.
- **Risk_Pack**: A thin overlay for a high-risk change surface that answers when
  the pack is primary, which supporting packs co-occur, which sync points are
  easy to miss, and which focused verification commands should run. Available
  packs: `runtime-streaming`, `ffi-boundary`, `observability-metrics`,
  `docs-tooling-drift`, `nginx-protocol-safety`, `release-governance`,
  `harness-remediation`.
- **Routing_Manifest**: The canonical machine-readable routing source at
  `docs/harness/routing-manifest.json` that maps change surfaces to risk packs
  and verification families.
- **Verification_Family**: A named group of verification commands organized by
  phase (cheap blocker, focused semantic, umbrella). Defined in the
  Routing_Manifest.
- **Cheap_Blocker**: A low-cost verification check that can identify obvious
  failures before deeper analysis. Examples: `make harness-check`,
  `make docs-check`.
- **Execution_Evidence**: Output from a real runtime execution target (not a
  plan-only or doc-only check) that demonstrates behavioral correctness.
- **Preflight_Review**: A harness review performed before implementation
  planning or edits for a Sub_Spec.
- **Postflight_Review**: A harness review performed after a Sub_Spec is written
  or updated.
- **Known_Difference**: A classified divergence between two conversion paths
  (for example full-buffer vs streaming) that has been explicitly categorized
  with drift type and severity, not silently suppressed.
- **Scope_Creep_Tripwire**: A condition that, if triggered, indicates the
  release is drifting beyond its stabilization mandate.
- **Truth_Surface**: A repo-owned file or directory that defines authoritative
  engineering rules, routing, or verification semantics. Local adapters and
  planning notes are not truth surfaces.
- **AGENTS.md (engineering contract)**: The `AGENTS.md` file, which is the
  Codex-first engineering rule map and the highest-priority repo-owned contract
  after the local development guide.

## Release Positioning

`0.5.5` is a **stabilization and correctness release**, not a feature-expansion
release. The release theme is **correctness, trust, and diagnosability**.

The release improves trust in the current architecture by tightening:

- **Semantic fidelity** — structural and semantic accuracy of HTML-to-Markdown
  conversion.
- **HTTP representation correctness** — protocol-level response handling
  including conditional requests, HEAD, and status codes.
- **Auth-aware cache safety** — cache-control directive rewriting that respects
  authentication state.
- **Streaming parity and fallback evidence** — measurable parity between
  full-buffer and streaming conversion paths with classified known differences.
- **Operator diagnosability** — reason-code taxonomy, runtime emission coverage,
  and logs/metrics/docs alignment.

If a Sub_Spec introduces a new public surface that is not required to close a
correctness gap, that introduction is classified as scope creep and must follow
the scope creep tripwire response protocol defined in this document.

## Scope Summary and Sub-Spec Decomposition

The release is decomposed into exactly six Sub_Specs numbered 20 through 25.
Each Sub_Spec addresses a distinct correctness surface:

| Sub-Spec | Title | Correctness Surface |
|----------|-------|---------------------|
| 20 | Semantic Fidelity | Structural and semantic accuracy of conversion |
| 21 | Protocol Correctness | HTTP response handling and conditional requests |
| 22 | Auth / Cache Safety | Auth-aware cache-control directive rewriting |
| 23 | Streaming Parity & Evidence | Full-buffer vs streaming parity and fallback |
| 24 | Operator Diagnostics | Reason-code taxonomy and runtime emission |
| 25 | Release Gate & Docs Sync | Documentation consistency and release gates |

The decomposition exists because each surface has a distinct primary Risk_Pack,
distinct verification commands, and distinct acceptance criteria. A single
monolithic spec would conflate routing, make verification matrices unwieldy, and
make change control ambiguous.

Sub_Specs are prohibited from redefining global rules already owned by this
Release_Spec. When a Sub_Spec references a shared term from this Release_Spec,
the Sub_Spec shall use the Release_Spec definition without contradiction or
duplication.

## Shared Principles

1. All requirements across the spec set are written as invariants, bounded
   behavior rules, verification obligations, or acceptance thresholds.
2. Vague activity statements such as "add docs", "add tests", or "improve
   quality" are prohibited unless tied to a concrete behavioral outcome.
3. Implementation work derived from any Sub_Spec obeys the engineering contract
   defined by `AGENTS.md`, including NGINX-style C conventions, C99-or-newer
   syntax, bounded allocations, explicit runtime guards, and the repository
   comment and pointer-safety rules.
4. Structural and semantic fidelity are preferred over cosmetic normalization
   across all Sub_Specs.
5. Docs, tests, metrics, and runtime behavior must describe the same thing for
   any changed public surface.

## Global Invariants

1. **Fidelity over cosmetics.** Structural and semantic fidelity are preferred
   over cosmetic normalization.
2. **Execution evidence required.** Runtime-sensitive work requires
   Execution_Evidence — output from a real runtime execution target, not a
   plan-only or doc-only check.
3. **Alignment across surfaces.** Docs, tests, metrics, and runtime behavior
   must describe the same thing for any changed surface.
4. **Classified known differences.** Known_Differences must be classified with
   drift type and severity, not dumped into a loose exception list.
5. **Harness alignment.** Routing and verification must stay aligned with the
   Harness defined in `docs/harness/`.
6. **Changeset completeness.** If a public surface changes, matching docs,
   tests, metrics, and Harness updates are required in the same changeset.

## Global Non-Goals

The following are explicitly out of scope for `0.5.5`:

- A new operator-facing extraction DSL.
- A broad observability platform rewrite.
- Default-on streaming preparation.
- Unchecked corpus growth without semantic classification.
- Speculative surface area that does not map to a current correctness gap.

Sub_Specs are prohibited from covering implementation details that belong to a
different Sub_Spec. Sub_Specs are prohibited from defining per-file code paths
or subsystem-specific acceptance criteria that belong to a different Sub_Spec.
No Sub_Spec may rely on local adapter behavior that does not belong to
repo-owned Truth_Surfaces.

## Spec Routing Model

### Sub-Spec to Risk Pack and Verification Family Routing

Every Sub_Spec names a primary Risk_Pack and any supporting packs. Routing
references bind to Verification_Family names (for example `ffi-boundary`,
`nginx-streaming`) rather than to specific `make` target names, so that command
renames in the Makefile do not require spec amendments. The concrete commands for
each family are resolved through `docs/harness/routing-manifest.json` at
execution time.

| Sub-Spec | Title | Primary Routing | Supporting Packs | Verification Families |
|----------|-------|-----------------|------------------|-----------------------|
| 20 | Semantic Fidelity | `ffi-boundary` | `observability-metrics` | `harness-sync`, `ffi-boundary` |
| 21 | Protocol Correctness | `nginx-protocol-safety` | `observability-metrics`, `ffi-boundary` | `harness-sync`, `nginx-protocol`, `ffi-boundary` |
| 22 | Auth / Cache Safety | `nginx-protocol-safety` | `observability-metrics`, `ffi-boundary` | `harness-sync`, `nginx-protocol`, `ffi-boundary` |
| 23 | Streaming Parity & Evidence | `runtime-streaming` | `observability-metrics`, `ffi-boundary` | `harness-sync`, `rust-streaming`, `nginx-streaming`, `runtime-e2e` |
| 24 | Operator Diagnostics | `observability-metrics` | `docs-tooling-drift` | `harness-sync`, `observability-metrics` |
| 25 | Release Gate & Docs Sync | `release-governance` | `docs-tooling-drift`, `observability-metrics` | `harness-sync`, `docs-tooling`, `release-governance`, `release-quality` |

The semantic fidelity workstream uses the existing `ffi-boundary` manifest entry. The protocol correctness and auth/cache safety workstreams use the existing `nginx-protocol-safety` risk pack. The release gate and docs sync workstream uses the existing `release-governance` risk pack. No new routing pack is implied or required for `0.5.5`.

### Routing Rules

- When a change spans two Sub_Specs, the conflict must be resolved through the
  Change Control section of this Release_Spec before implementation proceeds.
- When the Routing_Manifest does not clearly map a change to a single Sub_Spec,
  the routing must be fixed or the Sub_Spec must be split before implementation
  planning.
- Routing and verification must stay aligned with the Routing_Manifest defined
  in `docs/harness/routing-manifest.json`.

## Verification Policy

### Phased Verification Structure

Every Sub_Spec organizes its verification into three phases:

| Phase | Purpose | Examples |
|-------|---------|---------|
| Cheap Blockers | Catch obvious failures fast | `make harness-check`, `make docs-check` |
| Focused Semantic | Pack-specific behavioral checks | Commands resolved from the Routing_Manifest per verification family |
| Umbrella | Broad runtime and release checks | `make harness-check-full`, runtime smoke checks |

Command names in this table are illustrative. `docs/harness/routing-manifest.json`
is the sole resolution source for family-to-command mapping. When executing
verification, agents resolve commands from the manifest, not from examples in
this spec or in Sub_Spec documents.

### Verification Rules

1. Runtime-sensitive work requires at least one executed verification target per
   session.
2. Cheap_Blockers are identified and run before deeper verification checks.
3. Verification commands match the touched surface as defined by the
   Verification_Family mapping in the Routing_Manifest.
4. No Sub_Spec may rely only on prose or static checks when runtime behavior
   has changed.
5. Every Sub_Spec separates its verification into phases: Cheap_Blockers,
   focused semantic checks, and broader umbrella checks.
6. When a verification phase raises the effective risk level above the initial
   route, the route changes accordingly.

## Harness Review Policy

Every Sub_Spec undergoes both a Preflight_Review and a Postflight_Review.

### Preflight Review Checklist

Before implementation planning or edits, confirm:

1. The workstream maps to the correct routing entry.
2. The primary and supporting Risk_Packs are correct.
3. The Cheap_Blockers are realistic and sufficient.
4. The runtime verification target exists and is appropriate.
5. The current Harness rules can express the change without ambiguity.
6. The Sub_Spec does not rely on an unsupported local adapter or note.

### Postflight Review Checklist

After the Sub_Spec is written or updated, confirm:

1. The Sub_Spec did not reveal a gap in routing, risk-pack coverage, or
   validation.
2. Any newly discovered Harness weakness is captured as a separate follow-up.
3. Repo-owned Truth_Surfaces remain consistent with the Sub_Spec.
4. No Sub_Spec conclusion silently depends on outdated Harness wording.
5. Any needed Harness change is called out explicitly.

### Harness Adjustment Decision Rule

If the Harness rules do not cleanly describe the change being specified, the
Harness must be updated or the Sub_Spec must be split before implementation
proceeds. Harness adjustments are made only when the current rules are
inaccurate, too weak, or ambiguous for the behavior being specified.

## Acceptance Model

### Per-Sub-Spec Acceptance

1. Completion of each Sub_Spec is tied to evidence, not code presence alone.
2. Every Sub_Spec runs its corresponding verification path at least once in the
   current session before being marked complete.
3. Newly added `#[ignore]` tests are executed explicitly with `-- --ignored`
   before closing the Sub_Spec item that introduced them.
4. Generated artifacts (fixtures, evidence packs) are verified for both
   existence and required shape (schema, required fields).

### Release-Level Acceptance

The release is accepted when:

1. All six Sub_Specs (20–25) pass their acceptance criteria.
2. No Postflight_Review has an unresolved gap.
3. Coverage standards are met (80% aggregate minimum, 90% for critical paths).
4. All runtime-sensitive Sub_Specs have at least one real Execution_Evidence
   target.

## Sub-Spec Index

| Number | Title | Primary Risk Pack | Status |
|--------|-------|-------------------|--------|
| 20 | Semantic Fidelity | Semantic fidelity surfaces (routes through `ffi-boundary` family) | Pending |
| 21 | Protocol Correctness | `nginx-protocol-safety` | Pending |
| 22 | Auth / Cache Safety | `nginx-protocol-safety` | Pending |
| 23 | Streaming Parity & Evidence | `runtime-streaming` | Pending |
| 24 | Operator Diagnostics | `observability-metrics` | Pending |
| 25 | Release Gate & Docs Sync | `release-governance` | Pending |

When a new Sub_Spec is added after the initial set, it is assigned the next
available number starting from 26.

## Shared Terms and Cross-Spec Dependencies

All shared terms are defined in the Glossary section of this document. Sub_Specs
reference those definitions without duplication or contradiction.

### Cross-Spec Dependency Rules

| Dependency Type | Rule |
|----------------|------|
| Shared term reference | Use this Release_Spec's definition without duplication or contradiction |
| Reason-code reuse (streaming parity → operator diagnostics) | May reuse reason-code names from the diagnostics Sub_Spec but must not redefine the taxonomy |
| Docs/release-gate influence (semantic fidelity, protocol correctness, auth/cache safety → release gate and docs sync) | Protocol and auth/cache Sub_Specs may influence docs and release gates but remain responsible only for their own behavioral acceptance criteria |
| Behavioral conflict between two Sub_Specs | Resolve through this Release_Spec's Change Control section before implementation |

## Change Control

1. When a change spans two or more Sub_Specs, the conflict must be raised in
   this Release_Spec's Change Control section before implementation proceeds.
2. Sub_Specs are prohibited from modifying global rules, shared terms, or the
   routing model without updating this Release_Spec first.
3. Any Harness change triggered by a Sub_Spec must be called out explicitly and
   reviewed against all other Sub_Specs for consistency.
4. If a Sub_Spec discovers that the Harness routing is insufficient, the routing
   must be fixed before the Sub_Spec proceeds with implementation.

## Scope Creep Tripwires

The following conditions are defined as Scope_Creep_Tripwires:

1. Introduction of a new public surface not required to close a correctness gap.
2. Addition of a new operator-facing DSL or query language.
3. Expansion of the streaming path to default-on without explicit re-scope
   approval.
4. Addition of corpus fixtures without semantic classification.
5. Introduction of speculative surface area that does not map to a current
   correctness gap.
6. Any Sub_Spec requirement that reads as a feature rather than a correctness or
   trust improvement.

### Tripwire Response Protocol

When a Scope_Creep_Tripwire is triggered, the change must be either:

- **Rejected** — the change is out of scope.
- **Deferred** — moved to a later release.
- **Re-scoped** — explicitly re-scoped with documented justification.

A scope-drift review is part of every Postflight_Review.

## Deferred Topics

The following topics are deferred to releases after `0.5.5`:

| Topic | Reason for Deferral |
|-------|-------------------|
| Default-on streaming transition | Requires explicit re-scope approval |
| Broad observability platform rewrite | Beyond stabilization mandate |
| New operator-facing extraction DSL | Feature work, not correctness |
| Generalized content-ranking engine | Feature work, not correctness |
| Broad CDN-specific cache promises | Beyond current architecture |
| Broad HTTP framework rewrite | Beyond stabilization mandate |
| Speculative rollout policy not yet approved | Not yet approved |

Sub_Specs are prohibited from implementing deferred topics unless an explicit
re-scope is approved and documented.

## Spec Self-Review Policy

Every Sub_Spec must be self-reviewed before handoff to implementation.

### Self-Review Checklist

When performing a self-review, check for:

1. **Placeholders** — `TBD`, `TODO`, or incomplete sections.
2. **Contradictions** — between goals, invariants, and acceptance criteria.
3. **Scope drift** — beyond the numbered workstream.
4. **Ambiguous requirements** — that could be interpreted in two different ways.
5. **Missing runtime evidence** — where runtime behavior is affected.

If a self-review finds any issue, the Sub_Spec must be corrected before
continuing to implementation.

## Truth Surface Governance

### Authoritative Truth Surfaces

The following files are authoritative Truth_Surfaces:

- `AGENTS.md`
- `docs/harness/README.md`
- `docs/harness/core.md`
- `docs/harness/routing-manifest.json`
- `docs/harness/routing-manifest.md`
- `docs/harness/risk-packs/README.md`

### Advisory-Only Planning Notes

Planning notes (including `0.5.5-specs-19-25.md` and
`docs/project/0.5.5-spec-prep.md`) are advisory only and must not override
repo-owned Truth_Surfaces.

### Governance Rules

- Durable repo truth must not be written into local adapters, helper surfaces,
  or optional local spec inputs.
- Optional local steering adapters must point back to `docs/harness/` and must
  not define stronger semantics than `AGENTS.md`.

## Implementation Guardrails

All implementation work produced under this spec set must meet the following
baseline requirements, as defined by `AGENTS.md`:

1. **NGINX return-code semantics.** Use `NGX_OK`, `NGX_DECLINED`, `NGX_AGAIN`,
   `NGX_DONE`, and `NGX_ERROR` with correct semantics.
2. **C style.** All C code follows NGINX style with C99-or-newer syntax and no
   `//` comments.
3. **Null and bounds guards.** Explicit null and bounds guards before
   dereference, arithmetic, or relational pointer operations.
4. **Pool-based allocation.** Pool-based allocation and bounded working sets in
   request paths.
5. **Test fixture alignment.** Test fixtures and generated docs stay aligned
   with the implementation.
6. **No durable truth in local adapters.** Durable repo truth must not be
   written into local adapters or helper surfaces.
7. **Regression tests.** Every bug fix is accompanied by at least one targeted
   regression test.

## Coverage and Evidence Standards

### Coverage Thresholds

| Scope | Minimum | Target | Verification Command |
|-------|---------|--------|---------------------|
| C module aggregate | 80% | 90% | `make coverage-c` |
| Rust converter aggregate | 80% | 90% | `make coverage-rust` |
| Critical paths (auth, error handling, FFI boundary, conditional requests) | 90% | 90% | Per-path verification |

### Evidence Requirements

1. Runtime-sensitive Sub_Specs must include at least one real
   Execution_Evidence target, not a plan-only or doc-only check.
2. Bounded-memory and performance evidence fixtures must use parser-visible
   padding (for example regular elements and text), not parser-discarded
   constructs such as HTML comments, so measured memory reflects real
   conversion work.

## Open Questions

No open questions at this time. Open questions discovered during Sub_Spec work
will be raised through the Change Control section.

## Appendix

### Verification Family Reference

The following verification families are defined in
`docs/harness/routing-manifest.json`:

| Family | Phase | Commands |
|--------|-------|----------|
| `harness-sync` | Cheap Blocker | `make harness-check` |
| `docs-tooling` | Cheap Blocker | `make docs-check` |
| `rust-streaming` | Focused Semantic | `make test-rust-streaming` |
| `nginx-streaming` | Focused Semantic | `make test-nginx-unit-streaming` |
| `nginx-protocol` | Focused Semantic | `make test-nginx-unit`, `make test-nginx-integration` |
| `ffi-boundary` | Focused Semantic | `make build`, `make test-rust` |
| `observability-metrics` | Focused Semantic | `make docs-check`, `make release-gates-check` |
| `release-governance` | Focused Semantic | `make release-gates-check`, `make release-gates-check-strict`, `make release-gates-check-055` |
| `runtime-e2e` | Umbrella | `make verify-chunked-native-e2e-smoke`, `make verify-streaming-failure-cache-e2e` |
| `release-quality` | Umbrella | `make harness-check-full` |

This table is informational. The Routing_Manifest is the authoritative source.

### Document Updates

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.5.5 | 2026-04-25 | Release spec | Initial release spec |
