Retire staged ContentRelease behavior and reconcile content specifications

Parent epic: #38
Owner architecture decision: #226 (closed)
Historical staged-row repair: #219
Direct-sync delivery slices: #273, #274, #275, #276, #277
Direct-sync validation evidence: #272
Projection/source baseline: #253

Product outcome

Finish the direct-sync migration only after every live reader, writer, management surface, job, test fixture, operational check, and rollback consumer has moved off the rejected staged lifecycle. Preserve accepted historical provenance in its successor archive, close the compatibility window explicitly, remove the obsolete ContentRelease candidate/ready/activate/rollback schema and code, and reconcile authoritative specifications, architecture notes, verification guidance, and runbooks with #226.

This is Slice F and the final contract/removal child of #38. It does not implement direct sync, public cutover, or management parity. It may start only after Slices A–E and #272 are accepted and deployed, all source/family observation and rollback windows are closed, and a then-current exhaustive consumer manifest is approved.

PM status — BLOCKED / retain needs grooming

Do not dispatch engineering. Current origin/main at face8e4808d65afbf0374d1ced7a88079950d663 still implements staged storage, candidate preparation, active-pointer reads, activation/rollback, and their tests. The successor interfaces, accepted predecessor SHAs, final source/family inventory, historical-provenance archive, receipt identities, observation-window outcomes, and exact contract-migration leaf do not exist yet.

The inventory below is a dated baseline for re-grooming, not deletion authorization. needs grooming remains until PM rebases it against the exact accepted predecessor tip, records the accepted manifest digest and every consumer disposition, and replaces all successor placeholders with real symbols/migrations/receipts.

Normative authority

• _docs/PROCESS.md: issue lifecycle, migration discipline, versioned verification, independent tester/PM gates, screenshots, and on-call ownership.
• _docs/specs/open-decisions.md, decision 1, and closed #226: direct sync is authoritative; ordinary synchronization has no site-wide candidate, activation pointer, or rollback graph.
• _docs/specs/01-platform-architecture.md and _docs/architecture/app-boundaries.md: one Django deployment, domain-owned services, scalar durable jobs, after-commit side effects, and one-way dependencies.
• _docs/specs/03-github-content-and-people.md: source ownership, deterministic parsing, provenance, sanitization, route/link/asset safety, draft filtering, and freshness remain authoritative. Its staged model/activation passages are stale where they conflict with #226.
• _docs/specs/06-studio-and-admin-api.md: capability, revision, idempotency, masking, audit, and Studio/admin parity remain authoritative. Candidate preview/activate/rollback actions are not.
• _docs/specs/07-security-privacy-operations.md: redacted diagnostics, monitoring, retention, recovery, and no secret/PII leakage.
• _docs/specs/08-aws-development-terraform.md, _docs/specs/09-migration-rollout-roadmap.md, and _docs/specs/10-verification-strategy.md: exact-image release evidence, expand/reconcile/contract, portable migration tests, rollback compatibility, failure testing, and deployed gates remain authoritative after staged-content vocabulary is corrected.
• #219 owns preservation and repair of current historical staged rows. #273 must define the immutable successor provenance representation and copy/reconciliation evidence. Neither permits this issue to discard history.
• #274 and #275 own direct application, partial recovery, ingress, checkout, jobs, locks, and reconciliation. #276 owns public-reader/projection cutover. #277 owns Studio/admin API parity and removal of staged actions. #272 owns the accepted direct-sync content validation receipt/evaluator.
• #253 supplies the reproducible projection baseline used by #276. Conditional dependencies such as #44 for search/graph and #109 for any positive cache remain owned by their issues.

The generic application image/release controller in deploy/release.py, its deployment tests, and _docs/runbooks/development-release.md are not staged-content consumers merely because they say “release”, “active release”, or “rollback”. This issue must distinguish application rollback from rejected ContentRelease activation and must not remove or weaken the deployment controller.

Current consumer inventory baseline

Audit basis: clean origin/main/face8e4808d65afbf0374d1ced7a88079950d663 on 2026-08-30. Re-grooming must regenerate this inventory from the accepted Slice-E tip and bind canonical manifest bytes plus SHA-256. A path absent from this list is not implicitly safe to delete.

Runtime schema and persistence

• content/models.py: ContentSource.active_release; ContentRelease and all eight staged statuses; based_on_release; lifecycle/provenance/count/build/digest fields; ActiveContentPath; release-bound ContentDocument, ContentRelation, and ContentAsset; frozen-release mutation guards and release-specific asset storage identity.
• content/migrations/0001_initial.py through 0006_finalize_content_release_contract_digest.py: staged source/release/child/pointer schema, active-path claims, structured data, and #219 contract-digest compatibility history.
• content/migration_validators.py and _docs/architecture/database-portability.md: validators and portable constraints used by those tables/claims; keep any validator still owned by direct-sync rows.

Runtime services, selectors, and adapter seam

• content/services.py: create/transition/fetch/validate/prepare/ready/invalid/failed lifecycle; release-frozen child preparation; candidate readiness and path/asset/relation validation; active-path replacement; atomic activate/rollback swaps; lifecycle audit.
• content/queries.py: public document/asset resolution by status=active and ContentSource.active_release_id.
• content_sync/dtc_content/preparation.py and content_sync/dtc_content/__init__.py: PreparedCandidateResult, existing-release replay, candidate creation/preparation/readiness, and release-bound document IDs.
• On this baseline, no production Studio route, admin API route, public view, or job wrapper imports the staged commands directly. The public staged selectors are exercised through test-only content/tests/fixture_views.py and content/tests/fixture_urls.py. Re-grooming must prove this absence again; future predecessor work may add or replace consumers.

Tests, fixtures, and migration evidence

• content/tests/factories.py, content/tests/test_services.py, content/tests/test_queries.py, content/tests/test_inventory.py, content/tests/test_activation_concurrency.py, and content/tests/test_migrations.py.
• content/tests/fixture_views.py and content/tests/fixture_urls.py.
• content_sync/tests/test_dtc_content_preparation.py, test_dtc_content_accepted_checkout.py, and test_dtc_content_material_database.py.
• playwright_tests/test_content_release_primitives.py.
• test_support/factories/current_domain.py, test_support/migration_seeds/content-contract-digest-v1.json, and test_support/tests/test_migrations.py.
• core/tests/test_deployment_release.py contains a generic application active-release race test; classify it as application deployment unless a then-current assertion actually inspects staged content state.

Tests that establish preserved security, sanitization, collision, route, asset, relation, concurrency, portability, or historical-provenance behavior must be rewritten against direct-sync ownership and immutable history, not simply deleted with their old fixtures.

Specifications, architecture, planning, and runbooks requiring reconciliation

At minimum inspect and disposition every staged-content statement in:

• _docs/specs/01-platform-architecture.md: last-known-good principle, app ownership, data ownership, public read flow, content refresh, operations/failure statements.
• _docs/specs/03-github-content-and-people.md: Studio actions, ContentSource, ContentRelease, release-bound children/assets, candidate preparation, activation, rollback, invalidation, and freshness.
• _docs/specs/06-studio-and-admin-api.md: releases and activation/rollback management resources.
• _docs/specs/07-security-privacy-operations.md: content-release log vocabulary, updated without reducing redaction requirements.
• _docs/specs/08-aws-development-terraform.md: content-activation invalidation language; preserve separate application-release invalidation/rollback contracts.
• _docs/specs/09-migration-rollout-roadmap.md: retained-content-release fallback language and expand/reconcile/contract ordering.
• _docs/specs/10-verification-strategy.md: atomic activation/partial-release scenarios, replaced by direct-sync partial/status/recovery and projection contracts.
• _docs/architecture/app-boundaries.md, _docs/architecture/database-portability.md, and _docs/architecture/shared-primitives.md.
• _docs/planning/guideline.md and _docs/planning/wiki/synthesis.md: non-authoritative stale staged guidance must be corrected or clearly archived, never left as competing current direction.
• _docs/runbooks/ through an exhaustive textual and semantic audit. Generic deployment, package, or application-image “release/rollback” wording is preserved unless it incorrectly depends on staged content.

_docs/specs/open-decisions.md remains the decision record and must not be rewritten to obscure #226. Point-in-time audits remain historical records; add a superseding note only where readers could mistake one for current procedure.

Required final consumer manifest

Before grooming exit, create a versioned code-owned manifest/test whose exact bytes and SHA-256 are recorded in this issue. Each row must include:

1. tracked path and stable symbol/model/table/field/migration/API-route/job/spec-section identity;
2. consumer kind: runtime read, runtime write, public selector, direct-sync adapter, job, Studio/API, migration, fixture/test, verification/deploy, spec, architecture, runbook, or historical record;
3. current authority and exact accepted predecessor SHA that introduced its final state;
4. final disposition: replace_direct, retain_provenance, remove_staged, rewrite_contract, or not_content_release;
5. exact successor symbol/table/receipt/spec section for every replacement;
6. removal migration/commit and proof reference, or bounded rationale for retention;
7. rollback/compatibility window and closure evidence where applicable.

CI must fail on an unclassified import, ORM lookup, database table/column, status literal, API/action, URL, setting, job name, fixture, migration seed, documentation phrase, or new tracked file that reintroduces candidate/ready/activate/rollback authority. The guard must use precise content-domain identities and avoid false positives on application/package releases.

Removal and migration contract

1. Freeze accepted predecessors

Record exact accepted and deployed SHAs for #219, #253, #273–#277, and #272, plus every manifest-named conditional dependency. Record the #276 authority-manifest digest, all source/family hold points, the #272 receipt contract/producer identity, and final healthy observation results. No open predecessor, pending HUMAN criterion, partial/failed/conflicting current evidence, unclosed rollback window, or unknown consumer permits this issue to proceed.

2. Prove direct authority and stop staged mutation

Before destructive contract migration:

• all public document, relation, asset, route, search, graph, sitemap, feed, homepage, SEO, and cache/invalidation consumers use accepted direct selectors or an explicitly retained non-database authority from #276;
• all sync/ingress/reconcile/manual paths use #274/#275 direct services and cannot create/transition/activate/rollback a staged row;
• Studio and admin API expose only #277 direct status/config/sync/retry/edit operations and return the accepted safe absence/error contract for removed staged actions;
• #272 evaluates only direct-sync state and successor provenance, never an active release pointer;
• no job, signal, command, fixture URL, test helper, or operational script can mutate staged state; database-level observation proves staged row counts and checksums remain unchanged throughout the final compatibility interval.

Disable/remove public and management entry points before dropping their storage. There is no compatibility shim that silently translates an activation command into direct sync.

3. Preserve historical provenance

#273 must supply the exact immutable successor archive/interface before grooming exit. The final contract must preserve, for every historical source/release/child/path claim required by #219 and policy, enough canonical evidence to prove original primary/stable identities, source and commit, sequence/status/timestamps, parser/render/public-contract digests, child counts/checksums, active-history relationship, and the copy/reconciliation provenance.

The engineer must generate before/after canonical inventories and digests from synthetic populated fixtures representing every supported historical status, old/new public-contract digest, active pointer, based-on chain, document/relation/asset/path claim, duplicate/conflict/quarantine condition, and empty source. Missing, ambiguous, unsupported, or mismatched history fails before any drop. No raw production content, secret, token, delivery payload, PII, or unbounded diagnostic is copied into reports.

Historical provenance is read-only and cannot be selected by public queries, restored as active content, synced as an older SHA, or exposed as a hidden rollback action. Retention/deletion policy belongs to the accepted archive contract; this issue does not infer a legal retention period.

4. Close rollback compatibility before contract

Use expand → reconcile → cut over → observe → close compatibility → contract.

The previous accepted application image and historical/checked reader remain available only for the exact #276-approved compatibility window. Rehearse the approved application-reader rollback before that window closes and prove it performs no staged write or direct-row rollback. Record the owner/on-call closure decision and exact last rollback-compatible image/schema/artifact identities.

After the destructive schema contract, an application image that imports staged models/services or expects the old columns is intentionally incompatible and must be rejected before service mutation by deployment/readiness policy. Recovery is forward with accepted direct-sync replay/current source history, not reverse migration, table recreation, arbitrary old-SHA sync, or pointer activation.

5. Contract schema and code in dependency order

The final engineer plan must be split if the accepted graph cannot be safely delivered in one lane. Required order is:

1. remove/replace remaining runtime imports, URLs, actions, jobs, selectors, settings, and exports;
2. rewrite durable direct-sync/provenance tests before deleting staged-only tests;
3. add a final read-only compatibility assertion proving zero staged mutations and complete archived provenance;
4. remove staged services and adapter preparation wrapper;
5. remove staged pointer/status/claim/child foreign-key dependencies and obsolete fields using portable Django migrations;
6. drop staged tables/columns only after the migration preflight revalidates the frozen inventory/digests and the accepted archive;
7. remove obsolete migration fixtures only when replacement forward/historical migration coverage exists;
8. reconcile specs, architecture, verification guidance, and runbooks in the same accepted contract or an explicitly ordered documentation child that lands before #278 closes.

Historical migration files remain immutable. Add forward migrations; never edit squashed/applied history, fake migration state, use vendor-only SQL, or destructively reverse a deployed migration.

6. Rollback/failure behavior during migration

A preflight, copy, digest, constraint, schema, readiness, or service-start failure stops before web/worker mutation and leaves the prior exact application pair active under the deployment controller. A transaction failure leaves staged storage and archive state at the last committed compatible boundary; replay is deterministic and idempotent. No failure path falls back at request time, resurrects staged actions, rewinds direct rows, or reports complete #272 evidence.

Acceptance criteria after blockers are resolved

• [HUMAN] Every source/family in the #276 authority manifest has completed cutover, observation, and rollback rehearsal; the owner/on-call explicitly closes the staged-reader compatibility window and records the last compatible image/schema/artifact identities.
• [AUTO] #219, #253, #273–#277, #272, and every conditional manifest dependency are accepted and deployed. The issue records exact SHAs, migration leaves, successor symbols, receipt/manifest/report digests, and contains no placeholder interface.
• [AUTO] The regenerated consumer manifest is exhaustive and digest-bound. A repository guard detects every staged model/field/status/service/query/job/action/fixture/doc consumer and every direct ORM/import bypass, while distinguishing generic application/package releases.
• [AUTO] All runtime public, sync, job, Studio, admin API, receipt, and operational consumers use accepted direct authority. Old preview/prepare/ready/activate/rollback routes and commands are absent or return their explicitly accepted safe unavailable contract; no shim mutates direct state.
• [AUTO] A frozen compatibility-window observation proves zero staged writes while direct sync, reconciliation, public traffic, management reads/actions, receipt evaluation, and failure recovery operate normally.
• [AUTO] Populated forward-migration tests cover clean install and every supported historical staged state/digest/relationship. Exact before/after identities, counts, checksums, route/asset/relation evidence, and archive digests reconcile; apply/replay is idempotent; ambiguous or tampered input fails before drop with no data loss.
• [AUTO] Public/runtime tests prove draft/soft-deleted/disabled/quarantined/cross-source/raw/history rows remain non-public; direct current state, partial recovery, source ownership, routes, assets, relations, search/graph, cache/invalidation, and #272 evidence remain unchanged by retirement.
• [AUTO] Concurrency/fault tests cover a stale old application, staged mutation attempt, migration race, direct sync during the contract fence, archive mismatch, database failure, worker crash, retry, and readiness failure. None yields dual write, mixed authority, duplicate provenance, staged resurrection, direct-row rewind, or request-time fallback.
• [AUTO] Specifications 01/03/06/07/08/09/10, architecture boundaries/portability/shared primitives, planning guidance, and applicable runbooks consistently describe direct sync, source-scoped draft transition, observable partial recovery, immutable SyncLog/source status, direct selectors, forward correction, and application-image rollback. No normative text prescribes staged content activation.
• [AUTO] Generic application image/release/rollback, package release, database migration rollback safety, and deployment compensation remain intact and tested; textual cleanup does not conflate them with retired staged content.
• [AUTO] Required uv/Make verification passes: focused content/content-sync/migration/query/API/Studio/job/receipt/projection tests; migration drift and full migration matrix; portability; quality/type; complete Django; graph-selected Playwright tier; container; documentation/spec guards; and the versioned change-selective plan with exact base/head/graph/plan/report/artifact/manifest digests.
• [AUTO] Screenshots are not_applicable only if the final diff contains no template, static, route, navigation, copy, or rendered-state change, with the tester recording that exact reason. Any rendered impact requires desktop/mobile route/state screenshots under .tmp/screenshots/issue-278/ and full applicable browser verification.
• [HUMAN] The merged exact image passes migration-before-service-mutation, database-aware readiness, web/worker identity, public and management smoke, direct-sync/reconciliation/status/receipt checks, monitoring, and the accepted post-contract observation period. The obsolete schema/actions remain absent and no new public 5xx, route, canonical, asset, search/graph, or cache regression appears.
• Engineer, independent tester, PM, and on-call reports record exact identities/digests, commands/counts, migration and rollback-window outcome, redaction, every rerun/reuse/skip/not-applicable disposition, and any split child ordering.

Explicit non-goals

• No engineering while needs grooming remains; no deletion based on this dated baseline.
• No implementation or redesign of #219, #253, #272, #273–#277, #44, #109, or their accepted interfaces.
• No early drop/rewrite of historical migrations, staged tables, fields, rows, children, claims, tests, fixtures, or rollback artifacts before exact replacement and window closure.
• No restoration of candidate preview, prepare/ready, activation pointer, rollback graph, arbitrary older-SHA sync, automatic database rewind, hard delete, dual writer, or request-time fallback.
• No source/family authority decision, content import, source pin repair, route/search/graph/cache/asset/SEO/design/content rewrite, provider/AWS policy change, or production data operation.
• No weakening of sanitization, path collision, ownership, draft visibility, provenance, audit, idempotency, concurrency, portability, redaction, readiness, or deployment compensation because their staged test harness is removed.
• No removal or semantic weakening of the generic application release controller, application-image rollback, database migration recovery, package releases, or retained static artifacts still owned by an approved rollback manifest.
• No commit, push, merge, deployment, production access, AWS/provider mutation, Actions run, or local repository change during PM grooming.

Grooming exit

PM may remove needs grooming only when:

1. all required predecessors and HUMAN gates are accepted/deployed with exact SHAs and interfaces;
2. the #276 authority manifest, #272 receipt, successor provenance archive, last-compatible reader/image, rollback-window closure, and contract migration leaf are fixed and digest-bound;
3. a fresh audit of the accepted predecessor tip produces an approved exhaustive consumer manifest with no unknown/overlapping disposition;
4. every replacement names its actual successor symbol and every removal has migration/test/rollback evidence;
5. PM confirms the resulting work is one safely deliverable lane or splits it into ordered runtime, schema-contract, and documentation children.

Until then, #278 is specification work only and no engineer may dispatch it.

Begin only after Slices A–E and #272 are accepted, deployed, and their evidence is recorded. Regenerate the consumer manifest from the accepted tip, then audit content/models.py, content/services.py, content/queries.py, the listed migration and test files, and the named specifications and runbooks. Done means every consumer has a recorded disposition, historical provenance is retained, obsolete staged behavior is removed or reconciled, and migration and CI evidence passes.