Skip to content

Publish a real template release and exact core compatibility signal #12

Description

@Nickfost

Evidence on current main

Audited standalone-template main e483998b34595e51426c3b14589a74ca09ae78a9 against core main b76aefe668f07904e1a782fa5b779b606d6a44c9.

  • This repository currently has no tags and no GitHub releases, while docs/UPDATING.md says, "This template publishes tagged releases" and requires adopters to record a reviewed tag/object ID in TEMPLATE_RELEASE.
  • The update guide describes a collision-safe unrelated-history merge, tag-rewrite detection, vendored validator synchronization, and two-phase schema migration, but CI does not exercise that derived-repository flow against an actual release.
  • The standalone reference remains internally valid schema v3 and pins immutable core engine 8df97cc7575f47696fa82a179bbe39cd2874b1ca; that commit is reachable from current core main. The pin is not invalid merely because it differs from core main.
  • Core's embedded template has since added optional status-reporting schema/semantic validation, engine-rollout-evidence.json, staged capability checks, and related tests. The standalone schema/validator/examples do not include that optional extension, and neither repository has an automated exact-commit drift/freshness check connecting the two copies.
  • Standalone current-main validation passes, but it proves only internal agreement at the older reviewed contract. It does not tell an adopter which core/template pair was reviewed together or whether a newer core feature requires a template update.
  • There is no open or closed issue accurately tracking the missing release lifecycle and cross-repository freshness contract. Closed PR docs: add guide for keeping derived private repositories current #10 added the update guide, but the repository state it describes was never published.

User/operator impact

A new adopter cannot follow the documented tagged-release procedure because there is no release to select. An existing adopter has no machine-readable signal for the reviewed core/template combination, and optional core contract changes can remain absent from the standalone template without CI noticing. This makes safe immutable-pin updates unnecessarily dependent on repository archaeology.

Bounded scope

Establish the smallest real release and compatibility lifecycle:

  1. define a machine-readable reviewed compatibility record for an exact standalone-template commit/release and exact core commit(s);
  2. reconcile the standalone schema, semantic validator, initializer, examples, tests, and documentation with the chosen reviewed core contract without replacing immutable engine_ref values with branches or tags;
  3. add the rollout-evidence file and staged capability rules when importing optional status-reporting support;
  4. test a fictional derived repository through the documented TEMPLATE_RELEASE/unrelated-history update flow;
  5. publish the first immutable template tag/release only after those tests and review pass; and
  6. detect later drift between the standalone contract and the exact embedded-core contract it claims to match.

The compatibility record may support an older engine pin when optional fields are omitted. "Fresh" means reviewed and explicitly compatible, not numerically equal to core main.

Non-goals

  • Do not activate status reporting, deploy a receiver, provision credentials, or change infrastructure.
  • Do not advance the example engine_ref without a separate exact-commit compatibility review.
  • Do not use a moving core branch as executable configuration or validation input.
  • Do not require adopter telemetry or registration.
  • Do not rewrite an existing tag; release correction must use a new tag and documented supersession.

Cross-repository compatibility

  • The core installer consumes a vendored schema-v3 validator and gates optional status configuration on exact engine capabilities and staged rollout evidence.
  • Existing adopters that omit status_reporting must remain compatible with pre-capability engine commits.
  • A compatibility record must distinguish: schema support, validator/initializer version, optional engine capabilities, example pin, and the exact core commit used for review.
  • Core issue #24 should link the operator-facing release/update path; core issue #36 remains responsible for reproducible managed-image inputs, not template release tags.

Acceptance criteria

  • Repository has a documented initial immutable tag and GitHub release; release notes identify exact template and reviewed core commits.
  • Tag policy fails closed on rewrites; a correction uses a new immutable tag rather than retargeting an old one.
  • A machine-readable compatibility file states the exact reviewed core commit/contract and the status of the example engine pin.
  • Standalone schema, validator, initializer, reference config, multi-host example, tests, README, and CI agree with that compatibility record.
  • Optional status-reporting support, if included, ships with engine-rollout-evidence.json and the same two-step engine-capability migration checks as the reviewed core contract.
  • Existing configurations that omit optional status reporting continue to validate with the current immutable example pin unless an exact review proves a different pin is required.
  • CI creates a temporary fictional adopter repository, records TEMPLATE_RELEASE, performs the documented collision-safe update, preserves adopter-owned fleet.json, and validates the result.
  • CI compares this repository with the embedded core template at the exact compatibility commit and allows only documented intentional differences.
  • CI fails when a README/update-guide path or command references an unshipped required artifact.
  • Release/update documentation states how schema migration tooling is named and discovered when a future schema version actually ships.
  • No telemetry, credential, private endpoint, host inventory, or moving executable ref is introduced.

Validation

At minimum:

./scripts/validate.sh --strict
python3 scripts/test_policy.py
python3 scripts/scan_committed_secrets.py --commit <full-reviewed-commit>

Add one repository-local temporary-Git test for the documented release/update flow and one exact-commit core/template comparison test.

Dependencies

  • Operator cross-link/documentation ordering: core #24.
  • Optional status-reporting contract source: merged core #67 and deployment tracking in core #66; no live deployment is required.
  • Managed-image reproducibility remains core #36 and is parallel-safe.
  • The capability-aware deployment-policy issue in this repository may proceed in parallel, but both must land before the initial release is advertised as a complete delivery template.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions