Status: Active plan for issue #132

# Recovery release docs — model routing, compatibility, catalog, provenance

## Goal

Make release/model/provenance documentation describe the settled runtime rather than historical derivation notes or unqualified provider claims. Align catalog, workflow lock, README, architecture, changelog, provenance, and replacement-release notes to a single source of truth.

## Verified current behavior (evidence)

| Artifact | Location | Current state | Issue |
|---|---|---|---|
| Initial derivation edits table | `PROVENANCE.md:17-34` | 7-row Markdown table of EDIT 1–7 from 2026-06 derivation | Obsolete; the project has diverged far beyond these edits. CHANGELOG `§0.2.0` and `§0.1.0` are authoritative. |
| Upstream review stamp | `PROVENANCE.md:51` | "Last reviewed: 2026-07-02, upstream at v2.10.0" | Stale; upstream is now at v3.5.1. |
| `/fugu` alias | `workflow-lock.json` entry, `catalog.md`, README table | Listed as deprecated alias everywhere | Correct — preserve as-is. |
| Active profile | `docs/model-routing-specialization.md` tier table | Lists local Qwen / GLM-5.2 / GPT-5.6-Sol; GPT-5.5 in "Retired control" row | Correct posture, but GPT-5.5 row should explicitly label it as historical-control only in the "Recommended roles" section header. |
| `openai-codex` GPT-5.6 context | `docs/model-routing-specialization.md:175-186` | Correctly states 372k for Codex route, distinguishes from 1.05M API | Correct — no change needed, verify no doc contradicts this elsewhere. |
| Bundled-template kind | `workflow-lock.json:144` | `"kind": "bundled-template"` | Consistent with catalog `Lock schema notes`. |
| "bundled saved workflow" | `catalog.md:58` table column | Column says `bundled saved workflow` (human column label) vs. lock `kind: bundled-template` | Minor inconsistency: the human-readable table uses "bundled saved workflow" while the lock schema reserves `bundled-template`. Needs alignment. |
| README commands table | `README.md:~150` | `/fugu` row present, correct deprecated alias note | Correct. |
| 0.2.3 incompatibility notice | None | No dedicated release note identifying current-Pi incompatibility | Missing; 0.2.3 ships source incompatible with Pi ≥0.80.8. |
| CHANGELOG `[Unreleased]` | `CHANGELOG.md:5` | Empty | Needs docs entries for these provenance/catalog updates. |

## Dependencies

- **#129** (SDK compat restore) — blocks: provenance doc review may reference API contract changes.
- **#130** (AgentSession tool policy) — blocks: catalog/lock accuracy for Foundation workflow read-only boundary.
- **#131** (Foundation fail-closed) — blocks: README/architecture "bundled-template" vs "bundled saved workflow" wording settled by #131 contract.

All three dependencies must close before this doc cleanup is committed to avoid rewriting in-flight corrections.

## Allowed paths

- `PROVENANCE.md`
- `CHANGELOG.md` (`[Unreleased]` and the replacement-version entry when chosen)
- `README.md`, `docs/architecture.md`, `docs/workflows/catalog.md`, `docs/workflows/workflow-lock.json`, and Foundation docs as required to match the settled #131 source/registration contract
- `docs/model-routing-specialization.md` and `docs/provider-behavior-benchmarks.md` only for factual labeling/consistency—not to erase historical measurements
- the repository's existing `.release-notes/` convention for replacement-release notes; do not introduce a new root-level release-note convention without evidence

## Denied / out-of-scope

- Do not alter runtime source/tests/CI/package files in this docs issue; those belong to #129–#131.
- Do not delete `/fugu` or other required compatibility aliases.
- Do not remove historical benchmark evidence merely because GPT-5.5 is retired from active routing.
- Do not rewrite workflow-lock hashes by hand; regenerate/update them only through the documented checker after #131 changes the bundled template.
- Do not fabricate upstream outcomes or adoption decisions; cite the audited v3.5.1 concept ledger from #128/#133–#136.
- Do not change GitHub issue state.

## Dependency-ordered implementation steps

**Prerequisite:** Wait for #129, #130, #131 to close. Verify their PRs are merged.

### Step 1: Remove obsolete derivation table from `PROVENANCE.md`

- Delete `PROVENANCE.md:17-34` (the `## Initial derivation edits (historical)` heading and its 7-row table).
- Update the preceding paragraph (lines 5–7) to remove "the initial derivation edits" reference, keeping "origin" and "relationship to upstream".
- The `## Origin` section remains intact. The `## Relationship to upstream` section shifts up.

### Step 2: Update upstream review stamp in `PROVENANCE.md`

- At `PROVENANCE.md:51` (now shifted after Step 1), replace:
  `Last reviewed: 2026-07-02, upstream at v2.10.0. Outcome: one portable fix identified (share host ModelRegistry with workflow subagents, upstream #49) — tracked as #98; everything else already superseded by our own architecture.`
  with an evidence-based ledger along these lines:
  - **Adopted/proven independently:** the current-Pi ModelRuntime/session compatibility pattern and any concepts already present locally (for example atomic persistence backup) must be named accurately.
  - **Queued as bounded issues:** #133 persisted-state/retention, #134 fatal sibling drain + explicit-model errors + checkpoint identity, #135 loader retention + reload handoff, and #136 workflow control + usage-limit auto-resume.
  - **Rejected/deferred:** wholesale merges and upstream architecture that conflicts with this fork's harness broker/catalog contract.

Do not write “none identified”; the audit explicitly queued several concepts.

### Step 3: Align catalog terminology

- In `docs/workflows/catalog.md:58`, change the table column for `/foundation_ui_compliance` from `bundled saved workflow` to `bundled template` to match the lock `kind: bundled-template`.
- Verify the human-readable "Canonical workflows" table column header reads `Kind` and values are consistent.

### Step 4: Create replacement-release notes

Create/update `.release-notes/recovery-release.md` (matching the repository's existing release-note location) with:

- Title: `Release Notes — Recovery Release (post-0.2.3)`
- Section: 0.2.3 current-Pi incompatibility — explain that 0.2.3 ships against Pi 0.78 and is incompatible with Pi ≥0.80.8 until the recovery PR merges (#129/130/131).
- Section: Active model profile — local Qwen (small), GLM-5.2 (medium), GPT-5.6-Sol (big); GPT-5.5 is historical-control only.
- Section: `openai-codex` route context ceiling — 372k, not 1.05M.
- Section: `/fugu` compatibility alias — preserved as deprecated alias for `/issue-delivery`.

### Step 5: Update CHANGELOG `[Unreleased]`

Append to `CHANGELOG.md:5`:

```
### Documentation
- Remove obsolete "Initial derivation edits" table from PROVENANCE.md; the CHANGELOG and architecture docs are authoritative.
- Update upstream provenance review from v2.10.0 to v3.5.1 with adopted/queued/rejected ledger.
- Align catalog terminology: "bundled template" matches lock `kind: bundled-template`.
- Add `.release-notes/recovery-release.md` documenting 0.2.3 current-Pi incompatibility, active model profile, and Codex route ceiling.
```

### Step 6: Cross-doc consistency verification

Run targeted greps to confirm no contradictions remain:

```bash
grep -rn "Initial derivation" PROVENANCE.md  # should be empty after Step 1
grep -rn "v2.10.0" PROVENANCE.md  # should be empty after Step 2
grep -rn "1.05M.*openai-codex\|openai-codex.*1.05M" README.md docs/  # inspect context: accurate route-vs-direct-API distinctions are allowed
grep -rn "bundled saved workflow\|bundled-template" docs/workflows/  # consistent terminology
```

## Targeted tests

No source-code test changes. Verification:

```bash
npm run check        # TypeScript type-check (no source changes — should pass clean)
npm run build        # build gate
npm run check:workflow-lock  # lock integrity (no lock.json changes — should pass)
```

The full `npm test` gate is required before merge to ensure no latent breakage from dependency PRs (#129–131).

## Floor / latest compatibility verification

N/A — pure documentation work. However:

- The provenance upstream review notes must reflect the actual v3.5.1 release notes reviewed; do not fabricate adoption decisions.
- The 0.2.3 incompatibility statement in replacement-release notes must cite the Pi version range accurately (≥0.80.8, verified via #129).

## Acceptance checklist (mapped to issue #132)

- [ ] No normal routing/default/saved workflow pins GPT-5.5 → verified by grep; model-routing doc labels it "Retired control".
- [ ] Historical benchmark references remain labeled and reproducible → GPT-5.5 entries in benchmarks.md untouched.
- [ ] No doc claims 1.05M is usable through `openai-codex` → model-routing doc already correct; confirm no README contradiction.
- [ ] Catalog, workflow lock, command registration, README, architecture, changelog, provenance agree → Steps 1–5 align all artifacts.
- [ ] Full docs/lint/workflow-lock/package checks pass → Step 6 verification commands.

## Rollback / recovery

All changes are documentation-only and reversible via a single git revert. No runtime, test, or CI impact.

## Deferred work

- **Upstream review cadence:** Schedule a quarterly reminder for the next upstream review (target ~2026-10). File as a low-priority issue with a calendar note.
- **Recovery release note → CHANGELOG:** Once the replacement version is chosen, fold the final note into that versioned CHANGELOG entry while retaining or retiring the `.release-notes/` artifact according to the repository's established convention.
- **GPT-5.5 retirement from benchmarks.md:** Consider whether the `docs/provider-behavior-benchmarks.md` GPT-5.5 section (§109) should be moved to a historical appendix or archived, separate from this issue.