# 0.5.5 Spec Set: 19-25

This document is the executable planning output for the `0.5.5` spec set.
It defines the release-level structure, the six sub-specs, and the rules
future agents must follow when turning this plan into concrete spec files.

## Numbering Rule

- Preserve the current numbering.
- Generate the release-level spec as `19`.
- Generate the six workstream specs as `20` through `25`.
- Do not renumber existing specs.
- If new spec documents are required later, continue from `26`.
- Every generated spec file must include its number in the title and must not
  reuse an existing number for a different topic.

## Required Sources of Truth

Future agents must treat these as the authoritative repo-owned 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`
- the relevant risk-pack docs under `docs/harness/risk-packs/`

Planning notes are advisory only. They must not override repo-owned truth.

## Global Rules for All Specs

- Keep `0.5.5` a stabilization and correctness release, not a feature release.
- Write requirements as invariants, bounded behavior rules, verification
  obligations, or acceptance thresholds.
- Avoid vague activity statements such as "add docs", "add tests", or
  "improve quality" unless they are tied to a concrete behavioral outcome.
- Every spec must name a primary risk pack and any supporting packs.
- Every spec must separate cheap blockers from deeper verification.
- Every runtime-sensitive area must include at least one real execution
  target.
- Do not let plan-only checks or doc-only checks substitute for runtime
  evidence when runtime behavior is being changed.
- Any implementation work derived from these specs must continue to obey
  `AGENTS.md`, including NGINX-style C conventions, C99 or newer syntax,
  bounded allocations, explicit runtime guards, and the repository's comment
  and pointer-safety rules.
- If a public surface changes, the spec must say so explicitly and require the
  matching docs, tests, metrics, or harness updates in the same changeset.
- Before and after each spec, perform a harness review and decide whether the
  harness rules, routing, or validation guidance need to be adjusted.
- Before handing a spec to implementation, perform a spec self-review for
  placeholders, contradictions, scope drift, and ambiguity, then fix the text
  inline.

## Harness Review Policy

Every spec must include both a preflight and a postflight harness review.

### Preflight Harness Check

Before implementation planning or edits, confirm:

- the workstream maps to the correct routing entry
- the primary and supporting risk packs are correct
- the cheap blockers are realistic and sufficient
- the runtime verification target exists and is appropriate
- the current harness rules can express the change without ambiguity
- the spec does not rely on an unsupported local adapter or note

### Postflight Harness Check

After the spec is written or updated, confirm:

- the spec did not reveal a gap in routing, risk-pack coverage, or validation
- any newly discovered harness weakness is captured as a separate follow-up
- repo-owned truth surfaces remain consistent with the spec
- no spec conclusion silently depends on outdated harness wording
- if the harness should change, that change is called out explicitly

### Harness Adjustment Decision Rule

Adjust the harness only if the current rules are inaccurate, too weak, or
ambiguous for the behavior being specified. If the harness already covers the
behavior correctly, leave it unchanged and say so.

## Spec Self-Review Policy

Each generated spec must be reviewed before handoff. The review must check
for:

- placeholders such as `TBD`, `TODO`, or incomplete sections
- contradictions between goals, invariants, and acceptance criteria
- scope drift beyond the numbered workstream
- ambiguous requirements that could be interpreted in two different ways
- missing runtime evidence where runtime behavior is affected

If any issue is found, fix it in the spec text before continuing.

## Release-Level Workstream 19

### Title

`19. 0.5.5 Release Spec`

### Purpose

Define the release framing, shared principles, routing model, and change
control rules for the complete `0.5.5` spec set.

### Required Sections

- Purpose
- Release Positioning
- Scope Summary
- Shared Principles
- Global Invariants
- Global Non-Goals
- Spec Routing Model
- Verification Policy
- Harness Review Policy
- Acceptance Model
- Sub-Spec Index
- Shared Terms and Cross-Spec Dependencies
- Change Control
- Scope Creep Tripwires
- Deferred Topics
- Open Questions
- Appendix

### Must Cover

- `0.5.5` is a stabilization release
- correctness, trust, and diagnosability are the release theme
- why the release is split into six sub-specs
- how changes are routed to the correct sub-spec
- how cross-cutting issues are handled
- how runtime evidence is expected
- how harness review is performed before and after each spec
- what counts as scope creep
- what topics are deferred to later releases

### Must Not Cover

- implementation details for any single workstream
- per-file code paths
- subsystem-specific acceptance criteria
- local adapter behavior that does not belong to repo-owned truth

### Release-Level Invariants

- structural and semantic fidelity are preferred over cosmetic normalization
- runtime-sensitive work requires execution evidence
- docs, tests, metrics, and runtime behavior must describe the same thing
- known differences must be classified, not dumped into a loose exception list
- routing and verification must stay aligned with the harness

### Release-Level Verification Policy

- runtime-sensitive work must have at least one executed target
- cheap blockers must be identified before deeper checks
- verification commands must match the touched surface
- no spec should rely only on prose or static checks when behavior changed

### Release-Level Harness Reminder

If the harness rules do not cleanly describe the change, that is a signal to
update the harness or split the spec differently. Do not force the release
spec to absorb ambiguity.

## Implementation Guardrails

When these specs are turned into code, tests, docs, or comments, future
agents must also follow the repository implementation rules:

- use the correct NGINX return-code semantics
- keep C code in NGINX style with C99 or newer syntax
- avoid `//` comments in C
- use explicit null and bounds guards before dereference, arithmetic, or
  relational pointer operations
- prefer pool-based allocation and bounded working sets
- avoid blocking work in request paths
- keep test fixtures and generated docs aligned with the implementation
- avoid writing durable repo truth into local adapters or helper surfaces
- use concise, explanatory comments only where they add real value

## Semantic Fidelity Workstream 20

### Title

`20. 0.5.5 Semantic Fidelity`

### Purpose

Protect Markdown structural meaning across common and high-risk HTML content.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Corpus Strategy
- Known-Difference Policy
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- heading hierarchy
- nested lists
- tables
- blockquotes
- code blocks and inline code
- links, images, media, and fallback text
- front matter and metadata
- malformed HTML recovery
- cross-boundary preservation
- archetype-based corpus coverage

### Must Explicitly Decide

- what counts as structural loss
- what counts as acceptable drift
- what counts as review-required drift
- when a fixture becomes a regression fixture
- when a fixture becomes a known-difference fixture

### Must Not Cover

- a new content-extraction DSL
- a broad selector language
- a generalized content-ranking engine
- arbitrary corpus growth without classification

### Verification Expectations

- archetype-aware corpus checks
- golden output comparisons
- known-difference classification checks
- malformed and multibyte boundary cases
- regression coverage for the structural cases that matter most

### Harness Reminder

If the harness routing does not clearly map semantic fidelity work to the
correct risk pack, stop and fix the routing before implementation planning.

## Protocol Correctness Workstream 21

### Title

`21. 0.5.5 Protocol Correctness`

### Purpose

Make Markdown responses behave like a predictable negotiated HTTP
representation.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Request/Response Matrix
- Conditional Behavior Rules
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- `ETag`
- `Vary`
- `304 Not Modified`
- `HEAD`
- conditional request behavior
- representation metadata consistency
- full-buffer and streaming parity for protocol metadata

### Must Explicitly Decide

- when `ETag` is generated
- when `ETag` is compared
- what metadata must survive `304`
- how `HEAD` behaves
- which protocol differences, if any, are allowed between paths

### Must Not Cover

- a broad HTTP framework rewrite
- unsupported protocol matrix expansion
- behavior that is not grounded in the current implementation surface

### Verification Expectations

- request/response matrix coverage
- conditional request tests
- `304` and `HEAD` tests
- parity checks across full-buffer and streaming paths
- metadata ordering or body-ordering checks if relevant

### Harness Reminder

If the protocol matrix cannot be expressed cleanly in the harness truth
surfaces, the harness should be updated or the scope should be narrowed.

## Auth / Cache Safety Workstream 22

### Title

`22. 0.5.5 Auth / Cache Safety`

### Purpose

Ensure conversion never makes authenticated or personalized content more
publicly cacheable than it should be.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Detection Surfaces
- Cache-Control Rewrite Policy
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- `Authorization` header detection
- auth-cookie detection
- multiple `Cookie` headers
- `Cache-Control` rewrite behavior
- `public`, `private`, and `no-store`
- safe cache behavior under conversion

### Must Explicitly Decide

- which input surfaces define auth-aware behavior
- which cache directives can be rewritten
- which directives must never be weakened
- the precedence order between directives
- whether the conversion path preserves or upgrades safety

### Must Not Cover

- a generic personalization framework
- broad CDN-specific promises
- a new cache-policy DSL

### Verification Expectations

- directive rewrite unit tests
- auth-state integration tests
- cache policy matrix coverage
- mixed-directive cases
- multiple-cookie-header cases if relevant

### Harness Reminder

If auth/cache behavior is not represented in the current routing or evidence
model, define it explicitly before implementation work starts.

## Streaming Parity and Evidence Workstream 23

### Title

`23. 0.5.5 Streaming Parity & Evidence`

### Purpose

Prove that streaming behavior is correct at boundaries and that fallback
behavior is observable and classifiable.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Boundary Cases
- Fallback and Commit Semantics
- Evidence Model
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- chunk boundary behavior
- UTF-8 split handling
- fallback semantics
- pre-commit and post-commit failures
- parity against full-buffer output
- shadow or rollout evidence
- reason-code visibility for streaming decisions

### Must Explicitly Decide

- how `NGX_AGAIN` or equivalent backpressure is handled
- what state survives fallback
- which drift classes are acceptable
- what evidence operators should see
- whether evidence is human-reviewable, machine-reviewable, or both

### Must Not Cover

- default-on streaming conversion
- a broad telemetry redesign
- speculative rollout policy that is not yet approved

### Verification Expectations

- multi-boundary chunk tests
- multibyte UTF-8 boundary tests
- fallback tests
- full-buffer parity comparisons
- evidence format checks

### Harness Reminder

If the current harness cannot describe accepted drift or fallback evidence
clearly, that is a harness problem to fix, not a reason to weaken the spec.

## Operator Diagnostics Workstream 24

### Title

`24. 0.5.5 Operator Diagnostics`

### Purpose

Make skip, conversion, fallback, and degrade decisions explainable to
operators.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Reason-Code Taxonomy
- Logging and Metrics Mapping
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- skip reasons
- conversion reasons
- fallback reasons
- degrade reasons
- logs, metrics, and docs mapping
- operator-visible classification clarity

### Must Explicitly Decide

- the reason-code families that exist
- the runtime emission site for each defined reason code
- how each reason code is documented
- how degradation is classified for operational visibility
- how string-based classifiers are audited when new families are added

### Must Not Cover

- observability platform expansion
- unbounded high-cardinality logging
- open-ended reason-code sprawl

### Verification Expectations

- reason-code taxonomy checks
- runtime emission coverage
- logs/metrics/docs alignment
- classification coverage for any string-based reason routing

### Harness Reminder

If a reason code is defined but never emitted, or emitted but not documented,
the spec is incomplete and must be corrected.

## Release Gate and Docs Sync Workstream 25

### Title

`25. 0.5.5 Release Gate & Docs Sync`

### Purpose

Keep release gates, docs, metrics names, and harness references synchronized
with the real behavior of `0.5.5`.

### Required Sections

- Problem Statement
- Invariants
- Out of Scope
- Behavioral Rules
- Release Gate Structure
- Documentation Synchronization Rules
- Preflight Harness Check
- Verification Plan
- Postflight Harness Check
- Acceptance Criteria
- Open Questions

### Must Cover

- release checklist
- test matrix
- go/no-go criteria
- docs examples
- metrics naming and HELP text
- harness routing references
- version framing
- maintained docs alignment

### Must Explicitly Decide

- which docs must change with the behavior
- which checks are mandatory for release gating
- which verification commands require an explicit output format
- how metric names and docs must match exactly
- how public-surface changes trigger doc synchronization

### Must Not Cover

- a broad docs-system rewrite
- temporary planning notes as a substitute for repo truth
- command examples that do not match actual output formats

### Verification Expectations

- docs consistency checks
- naming consistency checks
- command example validation
- release checklist completeness checks
- scope-drift review against the release spec and sub-specs

### Harness Reminder

If a docs or release-gate statement cannot be validated against the current
harness and emitted behavior, it should be rewritten or removed.

## Cross-Workstream Reminders

- Workstreams 20-25 must not redefine the global rules already owned by the
  release-level workstream.
- Workstreams 20-25 may reference shared terms from the release-level
  workstream, but they must not
  duplicate or contradict them.
- Streaming diagnostics may reuse reason-code names from diagnostics, but they
  must not redefine the taxonomy.
- Protocol and auth/cache specs may influence docs and release gates, but they
  remain responsible only for their own behavior.
- If a change spans two workstreams, the conflict belongs in the release-level
  change control section first.
- If the behavior is not clearly covered by the current harness routing, fix
  the routing or split the spec before proceeding.

## Agent Instructions

Future agents generating or editing the numbered specs must:

- preserve numbering exactly
- keep the release-level spec at `19`
- keep the workstream specs at `20` through `25`
- use the repo-owned harness truth surfaces before making decisions
- check the harness before and after each spec
- explicitly decide whether the harness needs optimization or adjustment
- keep the spec focused on behavior, invariants, and evidence
- avoid turning a correctness release into a feature release
- avoid inventing new public surface unless the release explicitly requires it
- keep docs, metrics, tests, and runtime behavior aligned
- write in clear, professional English
