# 0.5.5 Spec Preparation Notes

This document is a working bridge between the two user-provided planning
notes and the repo-owned spec workflow. It captures the current alignment
state for release `0.5.5` so future spec decomposition can stay narrow,
verifiable, and consistent with the harness.

## Release Position

`0.5.5` is a stabilization release, not a feature-expansion release.

The release should improve trust in the current architecture by tightening:

- semantic fidelity of Markdown output
- HTTP representation correctness
- auth-aware cache safety
- streaming parity and fallback evidence
- operator diagnosability

## Working Interpretation

The release theme is: `Semantic Quality & Protocol Correctness`.

The intent is to make existing behavior more correct and easier to reason
about. It is not to introduce a broader extraction system, a new telemetry
platform, or a default-on streaming transition.

## Current Scope Buckets

The planning notes converge on six spec-friendly buckets:

1. semantic fidelity hardening
2. protocol correctness for conditional requests and representation metadata
3. auth and cache correctness
4. streaming parity, fallback semantics, and rollout evidence
5. operator diagnostics and reason-code clarity
6. release-gate and docs synchronization

## Non-Goals

The following are out of scope unless a later re-scope is explicit:

- 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

## Spec Decomposition Rules

Any sub-spec for `0.5.5` should answer these questions before implementation
planning begins:

- what exact risk or ambiguity is being reduced
- which invariant is being protected
- which risk pack is primary
- which supporting packs are likely
- what the cheapest blockers are
- which focused semantic checks are expected
- whether at least one runtime-executing verification target is required
- what "done" means beyond code existence
- whether the change adds a public surface
- if so, why that is unavoidable for `0.5.5`

## Suggested First Order

If the release is split into sub-specs, the preferred order is:

1. semantic fidelity and corpus/invariants
2. protocol correctness matrix
3. auth/cache correctness matrix
4. streaming parity and evidence
5. operator diagnostics
6. release-gate and docs sync

This order keeps correctness first, evidence second, and docs/gates last.

## Verification Stance

Runtime-sensitive work must include at least one real execution target.
Static checks alone are not sufficient for:

- streaming behavior
- conditional request handling
- cache/auth response semantics
- post-commit failure handling

Sub-specs should also separate:

- cheap blockers
- focused semantic checks
- broader umbrella checks
- optional release-quality checks

## Current Discussion Notes

The two provided planning notes agree on the following:

- `0.5.5` should stay narrow and correctness-focused
- requirements must be written as invariants, bounded behaviors, or
  verification obligations
- known differences and release gates should be treated as evidence systems,
  not as ad hoc exception lists
- local helper/adaptor layers must remain advisory and must not redefine repo
  truth
- final completion should be tied to evidence, not just code presence

## Open Questions for the Next Spec Pass

These are the main questions to settle when the actual spec set is written:

- which sub-specs deserve first-class scope instead of being folded into one
  broad release spec
- which current behaviors should be documented as intentionally accepted drift
- which runtime checks are mandatory for each change surface
- which docs and release-gate artifacts must be updated in the same changeset

