Merge pull request #62 from egohygiene/codex/aether-repository-release-contract

spec: define organization-wide repository release contract

Author: szmyty

.egohygiene/release.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://egohygiene.io/schemas/aether/repository-release/v1.json",
+  "schema_version": "egohygiene.repository-release/v1",
+  "repository": {
+    "id": "egohygiene/aether",
+    "lifecycle": "active",
+    "release_profile": "contract"
+  },
+  "release": {
+    "state": "unreleased",
+    "tag_prefix": "v",
+    "immutable_tags": true,
+    "major_alias": "optional"
+  },
+  "changelog": {
+    "path": "CHANGELOG.md",
+    "format": "keep-a-changelog/1.1",
+    "unreleased_heading": "Unreleased"
+  },
+  "components": [
+    {
+      "id": "first-party-artifacts",
+      "kind": "catalog",
+      "version_authority": {
+        "kind": "catalog-record",
+        "path": "catalog/first-party/catalog.v1.json",
+        "selector": "artifacts[*].artifact_version"
+      }
+    }
+  ],
+  "delivery": {
+    "channels": [
+      {
+        "kind": "github-release",
+        "state": "configured",
+        "relay_profile": "unavailable",
+        "notes": "Aether's release workflow publishes first-party skill evidence; Relay profile composition is planned."
+      }
+    ]
+  },
+  "evidence": {
+    "source": "required",
+    "change": "required",
+    "provenance": "required",
+    "sbom": "unavailable",
+    "signature": "unavailable",
+    "rollback": {
+      "strategy": "revert-and-successor-tag",
+      "instructions": "Revert the faulty default-branch change and publish a corrected successor tag; do not replace an immutable tag or release asset."
+    }
+  },
+  "automation": {
+    "taskfile_path": "Taskfile.yml",
+    "tasks": {
+      "plan": "release:plan",
+      "prepare": "release:prepare",
+      "verify": "release:verify",
+      "publish": "release:publish"
+    },
+    "github": {
+      "manual_dispatch_required": true,
+      "workflow_path": ".github/workflows/release-first-party-skills.yml",
+      "state": "configured"
+    }
+  }
+}

.github/copilot-instructions.md

@@ -45,6 +45,12 @@ Do **not** treat `.staging/`, `dist/`, or any other path as canonical source.
    canonical
    [`decision-impact.AGENTS.md`](../library/organization/projections/templates/decision-impact.AGENTS.md)
    module by reference; do not copy or weaken its Hygiene contract pins.
+8. **Follow the repository release declaration before changing versioning or
+   publication behavior.** Read [`AGENTS.md`](../AGENTS.md),
+   [`.egohygiene/release.json`](../.egohygiene/release.json), and the
+   [`repository-release`](../library/organization/specs/release/repository-release.spec.md)
+   specification. Release preparation is reviewable; publishing remains an
+   explicit manual, repository-owned action.
 
 ---
 

.github/workflows/release-first-party-skills.yml

@@ -1,9 +1,6 @@
 name: Release first-party skills
 
 on:
-  push:
-    tags:
-      - "v*"
   workflow_dispatch:
     inputs:
       release_tag:
@@ -15,7 +12,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: release-first-party-skills-${{ github.event.inputs.release_tag || github.ref_name }}
+  group: release-first-party-skills-${{ github.event.inputs.release_tag }}
   cancel-in-progress: false
 
 jobs:
@@ -37,17 +34,17 @@ jobs:
         id: release-context
         env:
           INPUT_RELEASE_TAG: ${{ github.event.inputs.release_tag || '' }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
           REF_NAME: ${{ github.ref_name }}
-          EVENT_NAME: ${{ github.event_name }}
         run: |
           set -euo pipefail
-          if [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
-            release_tag="${INPUT_RELEASE_TAG}"
-          else
-            release_tag="${REF_NAME}"
+          if [ "${REF_NAME}" != "${DEFAULT_BRANCH}" ]; then
+            echo "Dispatch this workflow from the default branch (${DEFAULT_BRANCH})." >&2
+            exit 1
           fi
-          if [[ ! "${release_tag}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.+][0-9A-Za-z.-]+)?$ ]]; then
-            echo "Release tag must match v<major>.<minor>.<patch>[suffix]" >&2
+          release_tag="${INPUT_RELEASE_TAG}"
+          if [[ ! "${release_tag}" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo "Release tag must match exact v<major>.<minor>.<patch>." >&2
             exit 1
           fi
           echo "release_tag=${release_tag}" >> "${GITHUB_OUTPUT}"
@@ -59,6 +56,14 @@ jobs:
           ref: ${{ steps.release-context.outputs.release_ref }}
           fetch-depth: 0
 
+      - name: Require tag on default-branch history
+        env:
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          git fetch origin "${DEFAULT_BRANCH}"
+          git merge-base --is-ancestor "$(git rev-parse HEAD)" "origin/${DEFAULT_BRANCH}"
+
       - name: Set up Python
         uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
@@ -190,14 +195,14 @@ jobs:
             -C dist skills github release
           echo "path=${archive_path}" >> "${GITHUB_OUTPUT}"
 
-      - name: Publish or reuse GitHub release
+      - name: Publish a new GitHub release
         run: |
           set -euo pipefail
           if gh release view "${RELEASE_TAG}" >/dev/null 2>&1; then
-            echo "Release ${RELEASE_TAG} already exists; skipping gh skill publish." | tee "${RUN_REPORT_DIR}/publish.txt"
-          else
-            gh skill publish "dist" --tag "${RELEASE_TAG}" | tee "${RUN_REPORT_DIR}/publish.txt"
+            echo "Release ${RELEASE_TAG} already exists; immutable release publication refuses to continue." >&2
+            exit 1
           fi
+          gh skill publish "dist" --tag "${RELEASE_TAG}" | tee "${RUN_REPORT_DIR}/publish.txt"
 
       - name: Attach release metadata assets
         run: |
@@ -208,8 +213,7 @@ jobs:
             dist/release/release-provenance.v1.json \
             dist/release/LICENSE.notices.txt \
             dist/release/release-notes.md \
-            "${{ steps.archive.outputs.path }}" \
-            --clobber | tee "${RUN_REPORT_DIR}/release-upload.txt"
+            "${{ steps.archive.outputs.path }}" | tee "${RUN_REPORT_DIR}/release-upload.txt"
 
       - name: Attest release archive provenance
         if: success()

.tasks/release.yml

@@ -0,0 +1,39 @@
+---
+# Repository-owned handoffs required by repository-release/v1. These commands
+# do not create a tag, publish an artifact, or use external credentials.
+
+version: "3"
+
+tasks:
+  release:plan:
+    desc: Validate Aether's release declaration and print a read-only plan
+    cmds:
+      - python3 "library/organization/specs/release/validate.py" --repository "." --format "json"
+
+  release:prepare:
+    desc: Preflight a reviewed Aether release candidate without mutating it
+    requires:
+      vars:
+        - RELEASE_VERSION
+    cmds:
+      - python3 "library/organization/specs/release/validate.py" --repository "." --release-version "{{.RELEASE_VERSION}}"
+      - echo "Prepare {{.RELEASE_VERSION}} in a reviewed release PR by promoting CHANGELOG.md Unreleased content and updating declared authorities."
+
+  release:verify:
+    desc: Verify a reviewed Aether release candidate before manual publication
+    requires:
+      vars:
+        - RELEASE_VERSION
+    cmds:
+      - python3 "library/organization/specs/release/validate.py" --repository "." --release-version "{{.RELEASE_VERSION}}" --format "json"
+
+  release:publish:
+    desc: Print the explicit manual release handoff after verification
+    requires:
+      vars:
+        - RELEASE_VERSION
+    cmds:
+      - task: release:verify
+        vars:
+          RELEASE_VERSION: "{{.RELEASE_VERSION}}"
+      - echo "Handoff only: create the immutable {{.RELEASE_VERSION}} tag from reviewed default-branch history, then manually dispatch .github/workflows/release-first-party-skills.yml."

AGENTS.md

@@ -0,0 +1,35 @@
+# Aether agent guidance
+
+Read this file before changing Aether. Canonical source is under
+`library/organization/` and `catalog/`; `.staging/` and `dist/` are derived or
+migration evidence, not source.
+
+## Release convention
+
+Every active Ego Hygiene repository follows the versioned
+[`repository-release`](library/organization/specs/release/repository-release.spec.md)
+contract. Its local declaration is `.egohygiene/release.json`; its root
+`CHANGELOG.md` retains an exact `## [Unreleased]` section.
+
+Before changing release behavior, inspect the declaration, version authority,
+changelog, existing immutable tags, and repository-owned release workflow.
+Use `release:plan`, `release:prepare`, and `release:verify` to make a reviewed
+candidate. `release:publish` is an explicit handoff only: do not create tags,
+publish packages, deploy sites, use registry credentials, or overwrite release
+assets unless the user separately authorizes that exact external action.
+
+Commit messages may inform a semantic-version recommendation, but the reviewed
+release plan and declared version authority decide the version. Follow the
+shared Conventional Commit work in `egohygiene/egohygiene#284` without letting
+it silently rewrite a release.
+
+## Aether boundaries
+
+Aether owns provider-neutral specifications, schemas, skills, and agent
+guidance. Relay owns reusable immutable execution; Hygiene owns applicability
+policy; Egolint owns conformance validation; Pace observes adoption before it
+proposes remediation. Keep provider credentials and delivery adapters in their
+consumer repository.
+
+Run the relevant deterministic validation and regenerate `dist/` and the
+first-party catalog after changing canonical source.

CHANGELOG.md

@@ -8,8 +8,11 @@ This repository follows release-tag based versioning for install pinning and rel
 - Installed skill pinning should use repository tags (for example `--pin "v1.0.0"`).
 - Artifact-level versions remain in frontmatter/catalog metadata and may evolve independently of repository tag cadence.
 
-## Unreleased
+## [Unreleased]
 
+- Added the versioned organization-wide repository release and changelog
+  contract, schema, migration guide, portable authoring skill, Aether
+  declaration, and safe Taskfile handoffs (#61).
 - Added the review-gated social campaign handoff specification, schema, and portable skill with exact Identity/catalog locks, candidate-only drafts, freshness and checklist gates, digest-bound human approval, external-adapter receipts, deterministic examples, and adversarial tests (#53).
 - Documentation overhaul for product-level README, contributor workflow, provenance, release/pinning, and safety guidance.
 - Added read-only PR validation and explicit tagged first-party skill release workflows with deterministic rebuild checks and release metadata generation.

README.md

@@ -44,8 +44,8 @@ Generated artifacts:
 ## 4) First-party catalog summary
 
 Current canonical inventory snapshot (recompute with the commands shown):
-- 25 specifications (`find library/organization/specs -name "*.spec.md"`)
-- 31 skills (`find library/organization/skills -name "SKILL.md"`)
+- 27 specifications (`find library/organization/specs -name "*.spec.md"`)
+- 33 skills (`find library/organization/skills -name "SKILL.md"`)
 - 9 canonical agent profiles (`find library/organization/agents -name "AGENT.md"`)
 
 Machine-readable catalog and provenance:
@@ -221,6 +221,12 @@ At present, GitHub CLI exposes `update` but no dedicated `remove` subcommand; re
 
 See `CHANGELOG.md` and `docs/release-and-pinning-guide.md`.
 
+Every active Ego Hygiene repository also declares its repository-level release
+profile, version authorities, changelog, evidence, and manual handoff in
+`.egohygiene/release.json`. The canonical convention and migration guide are
+[`repository-release`](library/organization/specs/release/repository-release.spec.md)
+and [repository release convention](docs/repository-release-convention.md).
+
 ## 13) External-skill provenance policy
 
 External skill records must be reconstructable from staged provenance evidence and validated against schema:

Taskfile.yml

@@ -6,6 +6,9 @@ version: "3"
 # Keep Taskfile as an ergonomic orchestration layer. Canonical implementation
 # remains in ./aether, GitHub CLI, and the repository's versioned build scripts.
 includes:
+  release:
+    taskfile: ./.tasks/release.yml
+    flatten: true
   skills:
     taskfile: ./.tasks/skills.yml
     flatten: true

catalog/README.md

@@ -9,6 +9,8 @@ provenance, lifecycle, and distribution.
 - `fixtures/` — valid/invalid examples per schema
 - `schemas/aether.social-campaign-handoff.v1.schema.json` — closed review,
   approval, immutable-export, and external-publication receipt contract
+- `schemas/aether.repository-release.v1.schema.json` — repository profile,
+  semantic-version, changelog, delivery, evidence, and manual-handoff contract
 - `first-party/catalog.v1.json` — canonical compatibility catalog for the current specification and skill corpus
 - `external/approved-skills.v1.json` — governed external skill catalog entries reconstructed from staged provenance
 - `external/source-candidates.v1.json` — non-publishable external source candidates, including their rights-review state