zone-engine/workplans/ZONE-WP-0002-reference-contract-hardening-and-retirement.md

id	type	title	domain	repo	status	owner	assignee	lane	topic_slug	planning_priority	created	updated	reviewed_at	reviewed_by	reviewed_against_commit	origin	context_paths	quality_dor	quality_dor_at	quality_dor_by	quality_dor_note	state_hub_workstream_id
ZONE-WP-0002	workplan	Harden the reference contract and make retirement decidable	infotech	zone-engine	active	zone-engine	codex	yellow	netkingdom	P1	2026-08-23	2026-08-23	2026-08-23	codex	d2ed3f0	history/2026-08-23-scope-against-intent.md	GOAL.md INTENT.md SCOPE.md docs/security-zones_v0.1.md docs/exception-lifecycle-2026-08-22.md tools/resolve_zones.py tests/test_resolve_zones.py	DoR-Ok	2026-08-23	codex	The gaps are evidenced against the implementation and canon; scope, owners, dependencies, verification, and stop conditions are explicit.	c349aa5c-d7fd-5c48-83aa-422cc42b9c67

ZONE-WP-0002 — Harden the reference contract and make retirement decidable

Goal

Make the repository safe to retain as a reference and safe to archive when its handoff is complete. Close the places where the checked-in resolver and local standard can overstate their authority or fall short of the canonical resolved view: canon lineage, workload-reference applicability, source-bound revisions, change observability, control-profile provenance, and exception conformance.

The workplan does not revive the rejected runtime. It leaves live decisions, control stance, failure behavior, exception grants, and exception expiry with their existing owners.

Why these gaps are the relevant ones

Priority	Gap	Why address it here
P0	Canon is authoritative but remains status: proposed; the local copy remains status: draft	Two independently editable normative-looking copies create lifecycle and drift ambiguity
P0	The resolver embeds an unversioned control profile	It can look like zone-engine owns stance, contrary to the load-bearing authority invariant
P1	The resolver omits the Repo Manager applicability/reference projection and full provenance	Its output is narrower than the canonical resolved-view contract and cannot distinguish unknown from explicit not-applicable inputs
P1	Membership revisions omit source revision and there is no previous-snapshot delta	The standard promises source-bound identity and observable membership changes
P1	Exception semantics have prose but no executable conformance fixtures	A reference repository should prove expiry and invalid-record rules without becoming the live evaluator
P1	Archive versus retained-reference ownership is not decided	The no-runtime falsifier fired; indefinite accidental maintenance is not an acceptable default

Estate-wide reference migration is intentionally excluded. Missing rapp references and unresolved catalog entries belong to their workload and catalog owners. This repo will consume an authoritative projection; it will not discover the fleet or infer a join.

Authority and dependencies

• net-kingdom owns canon publication and must rule on the canonical standard's lifecycle state and the durable source/mirror policy.
• repo-manager owns the v1 workload-reference tuple. This plan consumes RMGR-ADR-004 as-is and requests no placement or discovery authority.
• flex-auth owns its policy profile; ops-warden owns its controls and PEP failure modes. They review profile provenance and the integration replay.
• zone-engine owns the reference resolver, conformance fixtures, local evidence, and the final retirement recommendation.
• Operator action is required only for an actual Forgejo archive/rename or for accepting a continuing maintenance owner. Implementation can proceed through the archive-readiness evidence before that decision.

No dependency blocks T01 or the local contract work. External owner responses must arrive before T03 and T07 can be marked done.

Tasks

id: ZONE-WP-0002-T01
status: progress
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "d15053e8-d2a1-51ba-9a8f-45b899dbcab1"

Settle canon lifecycle and eliminate the duplicate-authority shape

Take the current state to net-kingdom: the canonical file is present and its adoption gates say complete, but its frontmatter is status: proposed, while the local source remains status: draft. Obtain and record the canon owner's ruling on:

1. the correct canonical lifecycle state;
2. whether this repository keeps a marked non-authoritative source snapshot, a verified mirror, or only a canonical pointer; and
3. how source revision and content identity are checked when canon changes.

Implement the ruling in this repository and offer the corresponding canon change to net-kingdom. A local normative-looking copy must not silently drift.

Done when: canon ownership and lifecycle are explicit; the local artifact cannot be mistaken for publication; a repeatable check detects lineage/content drift; and the owner ruling plus exact revisions are recorded under history/.

Verify: the lineage check passes against the reviewed canon checkout and fails against a deliberately altered fixture.

id: ZONE-WP-0002-T02
status: todo
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "2bbf0936-041c-548d-91af-2746925a88e8"

Bring membership resolution up to the canonical workload-reference boundary

Define and implement a versioned offline input contract that accepts:

• a direct authoritative workload declaration; or
• Repo Manager's already-resolved (rapp_id, workload_identity.name, deployable?) projection with explicit applicability.

The resolver must emit workload_ref, authoritative identity binding(s), declared and effective zone, admission and reason, membership guarantees, source reference, and source revision. Explicit not-applicable remains distinct from unresolved applicable input; absence or ambiguity returns unknown and never path- or repo-name inference.

This task does not add cross-repository discovery. The caller supplies the authoritative Repo Manager projection.

Done when: single-service, multi-service, managed-workload, direct operational-workload, unknown, unsatisfied, and not-applicable fixtures all produce the canonical shapes, and ambiguous identities are rejected.

Verify: unit tests cover every result class and prove that paths, repo ownership, reefs, actors, and lane names cannot manufacture membership.

id: ZONE-WP-0002-T03
status: todo
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "f2477679-e057-5dc9-87f1-0944e3f45642"

Remove implicit stance authority and require profile provenance

Separate membership/admission resolution from control-profile projection. Core resolution must work without any control profile. If controls are projected, require an explicit versioned profile owned by the relevant control and PEP owners; validate total coverage across all zone ids plus unknown and emit policy_owner, pep_owner, policy_ref or profile version, stance, and failure mode.

There must be no anonymous hard-coded default capable of appearing authoritative. A missing, partial, ambiguous, or ownerless profile fails profile projection without changing the membership result.

Have flex-auth and ops-warden review the fixtures that represent their rows.

Done when: changing zone-engine code alone cannot silently change a live control profile; every projected row carries owner and version provenance; and both affected owners accept the representative fixtures or publish a versioned replacement.

Verify: tests reject incomplete coverage, unknown control ids, missing owners, invalid stance/failure combinations, and unversioned profiles.

id: ZONE-WP-0002-T04
status: todo
priority: medium
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "91242013-3ab8-5a16-a479-a77eb0233bab"

Make membership revision and change observability truthful

Bind membership_revision to the canonicalized authoritative identity, membership declaration, and explicit source revision. Add deterministic comparison against a supplied previous snapshot and report additions, removals, and changes without consulting a service.

Define canonical ordering and serialization so identical facts produce the same digest across path locations and input ordering. A missing source revision must not produce a falsely source-bound digest.

Done when: the output meets the revision and observability claims in canon, including explicit handling for first snapshots and removed workloads.

Verify: golden tests prove stability, source-revision sensitivity, reorder insensitivity, and correct add/remove/change reports.

id: ZONE-WP-0002-T05
status: todo
priority: medium
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "9773cdc3-cc86-5cfb-bd00-fecaf68c8405"

Add executable exception-lifecycle conformance fixtures

Turn the minimum exception record and expiry rules into offline validation and deterministic fixtures. The checker receives an explicit evaluation instant; it does not read a live clock in a decision path and does not grant or store an exception.

Cover designated grant authority, owner-qualified control, exact workload and zone scope, exclusive not_after, maximum duration, renewal with a new id, invalid/unevaluable records being inactive, wildcard rejection, and the rule that durable authority cannot outlive the exception.

Done when: owners can reuse the fixtures to prove their implementation of the lifecycle while zone-engine remains neither grant authority nor runtime evaluator.

Verify: boundary-time and malformed-record tests cover before, active, exclusive-expiry, over-duration, wrong-authority, unknown-workload, overlap, and durable-expiry cases.

id: ZONE-WP-0002-T06
status: todo
priority: high
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "233c926f-00d4-5ebf-a867-154508c905d5"

Replay adoption against the hardened reference contract

Re-run the direct ops-warden and flex-auth declarations and add representative Repo Manager applicable and not-applicable projections. Confirm that membership digests, profile provenance, and exception fixtures are machine-readable and that consumer-owned suites still pass.

Record exact repository revisions, commands, outputs/digests, and owner review in a new evidence document. Do not require or deploy a zone-engine service.

Done when: the hardened resolver proves both existing adoption and the previously missing contract branches, and no consumer obtains stance or an authorization effect from an unversioned zone-engine default.

Verify: zone-engine tests and checks pass; affected owner test suites pass; canon validation passes; git diff --check is clean in every changed repo.

id: ZONE-WP-0002-T07
status: todo
priority: medium
quality_dor: DoR-Ok
quality_dor_at: "2026-08-23"
quality_dor_by: codex
state_hub_task_id: "aef75984-a5c4-573f-8fe4-90d1ee0ba695"

Reconcile present-state documentation and execute the retirement decision

Update README.md, INTENT.md, SCOPE.md, and GOAL.md so historical hypotheses are distinguished from current capability. Record the final answer:

• archive after canon lineage, fixtures, and evidence are durably owned; or
• retain as a reference-conformance repository with a named maintainer, canon-sync policy, and concrete change triggers.

An actual Forgejo archive or rename is an attended operator action. Do not take it merely because the technical checklist passes.

Done when: the documents agree, the archive/retain decision names its authority and date, no open task is hidden in prose, and either the attended archive is recorded or the continuing maintenance contract is explicit.

Verify: work-record consistency and quality-debt checks pass; the workplan has a DoD assessment; the final history record links all canonical and consumer revisions.

Acceptance criteria

• Canon lifecycle and local-copy lineage are owner-approved and mechanically checkable.
• The resolver represents direct, managed, unknown, unsatisfied, and not-applicable cases without inference.
• Membership revisions include explicit source revision and snapshot deltas are deterministic.
• Control projection is optional, versioned, total, and owner-provenanced; zone-engine owns no stance.
• Exception rules have executable offline fixtures without a runtime or live decision path.
• Existing consumer adoption is replayed with exact revisions and passing tests.
• Archive versus retained-reference ownership is explicitly decided and recorded.

Out of scope

• A zone-engine API, daemon, database, controller, scheduler, or synchronous lookup.
• Cross-repository fleet discovery or repair of missing workload references.
• Changes to Repo Manager placement/reef semantics or its v1 reference authority.
• Choosing flex-auth policy stance or an ops-warden PEP failure mode.
• Granting, storing, scheduling, or centrally expiring live exceptions.
• Migrating pre-rapp deployables or unresolved catalog entries for their owners.
• Renaming or archiving the Forgejo repository without attended operator approval.

Stop conditions

Stop and return to the relevant owner if implementation would require any of the following:

• inferring workload identity or applicability;
• making zone-engine's profile authoritative over an owner policy package;
• adding zone-engine to a live authorization or enforcement path;
• changing Repo Manager's v1 tuple rather than consuming it; or
• performing an unattended destructive archive/rename.