v1.0 Readiness Checklist

Plystra v1.0 Readiness Checklist

Document Status

Field	Value
Product	Plystra
Version	v1.0
Document Type	Release readiness checklist
Scope	Stable Self-Hosted Core
Status	Release Candidate gate
Owner	Core maintainers

---

1. Purpose

This checklist defines the release gate for Plystra v1.0.

Plystra v1.0 is considered ready for Release Candidate only when every required item in this document is completed, verified, and documented.

The goal is not to add more product scope. The goal is to prove that the v1.0 Core is stable, self-hostable, testable, explainable, and safe to upgrade.

v1.0 focuses on:

Stable Self-Hosted Core
Ent-backed Core schema
Core CRUD API
Resource Registry
Authorization check and explain
AuditLog
OpenAPI
Docker self-hosted baseline
Migration / drift / doctor tooling
Finance Reviewer demo cases

The following are not blocking v1.0:

Console
SDK repositories
Plugin runtime
Plugin marketplace
Data Console
Template installer
Cloud hosting
Enterprise SSO
Advanced policy engine

---

2. Release Scope Freeze

Before cutting v0.0.1, confirm that the v1.0 scope is frozen.

Required

• No new feature scope is being added to v1.0.
• Console is treated as optional and non-blocking.
• SDK repos are treated as optional and non-blocking.
• Plugin metadata is treated as optional enhancement and non-blocking.
• Plugin runtime is deferred after v1.0.
• Data Console is deferred after v1.0.
• Cloud hosting is deferred after v1.0.
• v1.0 remains Core-focused.

Acceptance Rule

If a proposed change does not directly improve one of the following, it must be deferred:

Core schema stability
Authorization correctness
Audit trace correctness
Resource Registry correctness
Migration safety
Self-hosted baseline
OpenAPI/API contract correctness
Release documentation

---

3. Clean Clone Quickstart Gate

A clean clone must be able to run using only README instructions.

Required

• A new developer can clone the repository.
• .env.example exists and is documented.
• README explains how to create .env.
• docker compose up -d starts required services.
• PostgreSQL becomes healthy.
• Plystra Core can be started locally.
• Migration command works.
• Demo seed command works.
• Doctor command works.
• Explain demo command works.
• README does not rely on undocumented local machine state.

Required Commands

The README quickstart should cover the equivalent of:

git clone https://github.com/plystra/plystra.git
cd plystra
cp .env.example .env
docker compose up -d
plystractl migrate up
plystractl migrate verify
plystractl doctor
go test ./...
go run ./cmd/explain-demo

If commands differ, the README must reflect the actual commands.

Acceptance Rule

A clean environment must be able to reach a working v1.0 demo without reading internal design documents.

---

4. Docker Self-Hosted Baseline Gate

v1.0 must provide a working self-hosted baseline.

Required Files

• Dockerfile
• docker-compose.yml
• .env.example
• README self-hosted section
• migration command documentation
• health check documentation

Required Services

• plystra-core
• postgres

Optional services must not be required for v1.0 startup unless explicitly documented.

Required Docker Compose Behavior

• docker compose up -d starts PostgreSQL.
• docker compose up -d starts Plystra Core if configured to do so.
• Environment variables are read from .env.
• Database connection settings work with the provided compose file.
• Container logs are readable.
• Container restart does not corrupt data.
• Volumes are named clearly.
• Production notes warn users about backup responsibility.

Acceptance Rule

A user should be able to self-host the v1.0 Core baseline with Docker Compose and PostgreSQL.

---

5. Migration Gate

Migrations are a release-blocking requirement.

Required

• Versioned migrations exist.
• Migration 010 exists if required by this development cycle.
• Migration 011 exists if required by this development cycle.
• Migrations apply to an empty database.
• Migrations apply from the previous release schema.
• plystractl migrate up works.
• plystractl migrate verify works.
• Migration status can be inspected.
• Failed migrations return clear errors.
• Production does not run Ent auto migration on startup.
• Production ent apply is intentionally rejected and documented.

Required Commands

plystractl migrate up
plystractl migrate verify
plystractl ent check

Empty Database Test

• Start an empty PostgreSQL database.
• Apply all migrations.
• Verify schema.
• Start Core.
• Run basic smoke tests.

Upgrade Database Test

• Start from the previous release schema.
• Apply migrations.
• Verify schema.
• Start Core.
• Run authz conformance tests.

Acceptance Rule

A release cannot proceed if migrations only work on the maintainer’s local database.

---

6. Ent Drift Gate

Ent schema, generated code, and database migrations must be synchronized.

Required

• plystractl ent check passes.
• Ent drift is zero.
• Generated Ent code is committed.
• Schema changes are reflected in migrations.
• CI fails on stale generated code.
• CI fails on missing migration files.
• CI applies migrations to an empty database.
• CI applies migrations from previous release schema.

CI Expectations

CI should include jobs equivalent to:

codegen-check
migration-diff-check
migration-apply-empty-db
migration-apply-upgrade-db
authz-conformance-test

Acceptance Rule

If Ent schema changes without corresponding generated code and migrations, CI must fail.

---

7. Core CRUD API Gate

v1.0 requires complete Core CRUD APIs for the stable Core entities.

Required Entities

• Users
• Spaces
• Groups
• Members
• UserMembers
• Roles
• Permissions
• MemberRoles
• RolePermissions
• Resources
• AuditLogs

Required Behavior

• Create works where applicable.
• Read single entity works.
• List entities works.
• Patch/update works where applicable.
• Disable/restore/revoke/archive workflows work where applicable.
• AuditLog has read/list only.
• AuditLog update is not exposed.
• AuditLog delete is not exposed.
• API responses include stable DTOs.
• API responses do not expose generated Ent structs.
• Validation errors return consistent error envelope.
• Request ID is included in responses.

Entity-Specific Requirements

Users

• Create user.
• Read user.
• List users.
• Patch user.
• Disable user.
• Restore user.

Spaces

• Create space.
• Read space.
• List spaces.
• Patch space.
• Disable space.
• Restore space.

Groups

• Create group under space.
• Read group.
• List groups.
• List group tree.
• Patch group display fields.
• Disable group.
• Group path immutability is documented and enforced.

Members

• Create member.
• Read member.
• List members.
• Patch member.
• Disable member.
• Restore member if supported.

UserMembers

• Create binding.
• Read binding.
• List bindings.
• Patch binding.
• Revoke binding.
• Restore binding if supported.
• Revoked binding denies authorization.
• Expired binding denies authorization.

Roles

• Create role.
• Read role.
• List roles.
• Patch role.
• Disable role.

Permissions

• Create permission.
• Read permission.
• List permissions.
• Patch permission if allowed.
• Disable permission.
• resource/action/scope uniqueness is enforced.

MemberRoles

• Create role grant.
• Read role grant.
• List role grants.
• Revoke role grant.
• scope_anchor_group_id is supported.
• Same-space constraints are enforced.

RolePermissions

• Create role-permission binding.
• Read binding.
• List bindings.
• Revoke/delete binding according to chosen design.
• Permission changes are audited.

Resources

• Register resource.
• Read resource.
• List resources.
• Patch resource.
• Archive resource.
• Resource can enter authz check chain.

AuditLogs

• List audit logs.
• Read audit log.
• Filter by actor.
• Filter by resource.
• Filter by decision.
• Filter by deny code.
• Filter by request ID.
• No update endpoint.
• No delete endpoint.

---

8. Health, Ready, and Version Gate

v1.0 requires standard operational endpoints.

Required New Endpoints

• GET /api/v1/health
• GET /api/v1/ready
• GET /api/v1/version

Required Behavior

/api/v1/health

• Returns basic service health.
• Does not require database access if intentionally designed that way.
• Returns clear JSON.

/api/v1/ready

• Checks database connectivity.
• Checks migration readiness.
• Returns non-ready if database is unavailable.
• Returns non-ready if schema is invalid.

/api/v1/version

• Returns Core version.
• Returns schema version.
• Returns trace version.
• Returns build metadata if available.

Acceptance Rule

Health endpoints must support self-hosted operations and smoke testing.

---

9. Authorization Gate

Authorization correctness is the most important release gate.

Required APIs

• POST /api/v1/authz/check
• POST /api/v1/authz/explain

Required Behavior

• Actor context includes user_id.
• Actor context includes space_id.
• Actor context includes member_id.
• Actor context includes user_member_id.
• Resource target includes resource type and ID.
• Action is required.
• User status is checked.
• Space status is checked.
• Member status is checked.
• UserMember status is checked.
• UserMember expiration is checked.
• Same-space constraints are checked.
• Candidate permissions are filtered by resource_type + action.
• Multiple matching grants use union semantics.
• Scope checks are evaluated for all candidates.
• NO_MATCHING_PERMISSION is returned when no candidate matches resource/action.
• SCOPE_OUT_OF_BOUNDS is returned when candidates exist but none covers scope.
• USER_MEMBER_REVOKED is returned for revoked binding.
• USER_MEMBER_EXPIRED is returned for expired binding.
• GLOBAL_SCOPE_DISABLED is returned for disabled global scope.
• Full explain trace includes matched candidates.
• AuditLog can be written for decisions.

Required Scope Behavior

• self uses resource.owner_member_id == actor.member_id.
• group uses direct group match.
• group_tree uses safe path matching.
• space uses same Space match.
• global is disabled.

Acceptance Rule

The Finance Reviewer demo and conformance tests must pass.

---

10. Resource Registry Gate

v1.0 must include a Resource Registry foundation.

Required

• Resource registration API exists.
• Resource records include resource_type.
• Resource records include space_id.
• Resource records support group_id.
• Resource records support owner_member_id.
• Resource records support metadata.
• Resource records can be used by authz/check.
• Resource records can be used by authz/explain.
• Resource changes are auditable.
• Invalid cross-space group assignment is rejected.
• Invalid cross-space owner assignment is rejected.

Acceptance Rule

A newly registered resource type must be able to enter the authorization chain without custom code.

---

11. AuditLog Gate

v1.0 requires reliable audit logs.

Required

• AuditLog is append-only.
• AuditLog update is blocked.
• AuditLog delete is blocked.
• AuditLog trace stores snapshot.
• AuditLog stores decision.
• AuditLog stores deny_code.
• AuditLog stores actor IDs.
• AuditLog stores resource target.
• AuditLog stores request ID if available.
• AuditLog query API exists.
• AuditLog filters work.
• Allow decisions can be audited.
• Deny decisions can be audited.

Trace Snapshot Required Fields

• trace_version
• decision
• deny code
• actor user snapshot
• actor member snapshot
• user_member snapshot
• space snapshot
• target resource snapshot
• matched candidates
• role snapshot
• permission snapshot
• scope anchor snapshot
• scope check result
• reason

Acceptance Rule

Historical audit logs must remain explainable even if live Role, Permission, Member, Group, or Resource records change later.

---

12. Finance Reviewer Demo Gate

v1.0 must include the four required demo cases.

Required Cases

Case	Actor	Target	Expected Decision	Required Proof
1	Alice via Finance Reviewer	Finance/APAC invoice	allow	group_tree works
2	Alice via Finance Reviewer	Legal/EMEA invoice	deny SCOPE_OUT_OF_BOUNDS	scope boundary works
3	Bob via same Finance Reviewer	Finance/APAC invoice	allow	multiple Users can share same Member
4	Alice via revoked binding	Finance/APAC invoice	deny USER_MEMBER_REVOKED	UserMember is independent authorization bridge

Required

• Demo seed data exists.
• Demo command exists.
• Expected output is documented.
• Demo output includes allow trace.
• Demo output includes deny trace.
• Demo output includes Bob shared Member case.
• Demo output includes revoked binding case.
• README references demo.
• Tests assert demo decisions.

Acceptance Rule

A developer reading the demo output should understand Plystra’s core model without reading the full PRD.

---

13. Request Logging and Recovery Gate

v1.0 must include standard request middleware.

Required

• Structured JSON request logs.
• Request ID generation.
• Request ID propagation.
• Recovery middleware.
• Panic returns safe error response.
• Panic logs include request ID.
• CORS configuration exists.
• Trusted proxy behavior is documented if relevant.
• Sensitive HTTP APIs require Bearer user session or endpoint-specific authentication.
• Data Console and metrics surfaces are disabled by default unless explicitly enabled.

Required Log Fields

timestamp
level
request_id
method
path
status
latency_ms
remote_ip
user_agent
error_code if present

Acceptance Rule

A production operator must be able to correlate request logs, API responses, and AuditLog entries.

---

14. API Envelope and Request ID Gate

v1.0 must document canonical request ID behavior.

Required

• Top-level request_id is returned.
• meta.request_id is not returned.
• OpenAPI documents only the canonical top-level field.
• Tests assert envelope shape.
• Release notes explain the canonical envelope.

Acceptance Rule

Clients should read the top-level request_id.

---

15. OpenAPI Gate

v1.0 requires an accurate OpenAPI document.

Required

• OpenAPI v1.0 exists.
• All implemented endpoints are documented.
• All documented routes exist.
• Request schemas match accepted payloads.
• Response schemas match actual responses.
• Error envelope is documented.
• Canonical top-level request_id behavior is documented.
• Deny codes are documented or referenced.
• OpenAPI matches handler behavior.
• CI or tests detect major route drift if possible.

Acceptance Rule

A future SDK can be generated from the OpenAPI schema without relying on undocumented response fields.

---

16. Documentation Gate

v1.0 must include documentation sufficient for self-hosting and integration.

Required Docs

• README
• Quickstart
• v1.0 readiness checklist
• v1.0 RC test plan
• v1.0 release notes
• migration and upgrade guide
• canonical request ID envelope doc
• OpenAPI v1.0
• authz check/explain guide
• Resource Registry guide
• AuditLog guide
• Ent integration guideline
• non-goals / scope document

Acceptance Rule

A developer should not need private project context to install, run, test, or understand v1.0 Core.

---

17. Final RC Gate

Before tagging v0.0.1, all of the following must pass:

go test ./...
PLYSTRA_DATABASE_URL=... go test ./...
plystractl migrate up
plystractl migrate verify
plystractl ent check
plystractl doctor

And smoke tests must pass for:

health
ready
version
authz/check
authz/explain
Resource Registry
Users CRUD
Spaces CRUD
Groups CRUD
Members CRUD
UserMembers CRUD
Roles CRUD
Permissions CRUD
MemberRoles CRUD
RolePermissions CRUD
Resources CRUD
AuditLogs query
disable
restore
revoke
archive

Final Acceptance Rule

If a clean environment cannot pass the quickstart, migrations, doctor, demo, and smoke tests, do not tag RC.

---

18. Sign-off

Area	Owner	Status
Scope freeze
Migration
Ent drift
Authz
AuditLog
Resource Registry
CRUD APIs
OpenAPI
Docker baseline
Docs
Release notes
Final RC tag