updated readme

Author: rcholic

.github/workflows/phase1-ci-and-release.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
   push:
     branches: ["main", "phase1"]
+    tags: ["v*"]
   workflow_dispatch:
     inputs:
       publish:
@@ -47,7 +48,7 @@ jobs:
   publish-predicate-contracts:
     runs-on: ubuntu-latest
     needs: [quality]
-    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'true'
+    if: (github.event_name == 'workflow_dispatch' && inputs.publish == 'true') || startsWith(github.ref, 'refs/tags/v')
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -63,6 +64,10 @@ jobs:
       - name: Verify release order
         run: python scripts/verify_release_order.py
 
+      - name: Validate release tag version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: python scripts/validate_release_tag.py --tag "${GITHUB_REF_NAME}"
+
       - name: Build predicate-contracts
         run: python -m build predicate_contracts
 
@@ -78,7 +83,7 @@ jobs:
   publish-predicate-authority:
     runs-on: ubuntu-latest
     needs: [publish-predicate-contracts]
-    if: github.event_name == 'workflow_dispatch' && inputs.publish == 'true'
+    if: (github.event_name == 'workflow_dispatch' && inputs.publish == 'true') || startsWith(github.ref, 'refs/tags/v')
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -94,6 +99,10 @@ jobs:
       - name: Verify release order
         run: python scripts/verify_release_order.py
 
+      - name: Validate release tag version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: python scripts/validate_release_tag.py --tag "${GITHUB_REF_NAME}"
+
       - name: Build predicate-authority
         run: python -m build predicate_authority
 

Makefile

@@ -1,8 +1,14 @@
-.PHONY: hooks lint test examples verify-release-order build-packages format format-python format-docs lint-docs dev-install
+.PHONY: hooks lint test examples verify-release-order build-packages format format-python format-docs lint-docs dev-install tag-release
 
 dev-install:
 	python -m pip install -e predicate_contracts -e predicate_authority
 
+tag-release:
+	@test -n "$(VERSION)" || (echo "Usage: make tag-release VERSION=X.Y.Z" && exit 1)
+	python scripts/validate_release_tag.py --tag "v$(VERSION)"
+	git tag -a "v$(VERSION)" -m "Release v$(VERSION)"
+	@echo "Created tag v$(VERSION). Push with: git push origin v$(VERSION)"
+
 hooks:
 	pre-commit install
 

README.md

@@ -5,6 +5,7 @@
 [![License](https://img.shields.io/badge/License-MIT%2FApache--2.0-blue.svg)](LICENSE)
 [![PyPI - predicate-authority](https://img.shields.io/pypi/v/predicate-authority.svg)](https://pypi.org/project/predicate-authority/)
 [![PyPI - predicate-contracts](https://img.shields.io/pypi/v/predicate-contracts.svg)](https://pypi.org/project/predicate-contracts/)
+[![Release Tag](https://img.shields.io/badge/release-vX.Y.Z-blue)](docs/pypi-release-guide.md)
 
 `predicate-authority` is a production-grade pre-execution authority layer that binds AI agent identity to deterministic state. It bridges standard IdPs (Entra ID, Okta, OIDC) with runtime verification so every sensitive action is authorized, bounded, and provable.
 
@@ -69,6 +70,9 @@ make dev-install
 # equivalent: python -m pip install -e predicate_contracts -e predicate_authority
 ```
 
+Release note: publish is supported by pushing a synchronized git tag `vX.Y.Z`
+(see `docs/pypi-release-guide.md`).
+
 For shared contracts directly:
 
 ```bash

docs/pypi-release-guide.md

@@ -49,6 +49,28 @@ python -m build predicate_authority
    - `publish-predicate-contracts`
    - `publish-predicate-authority` (runs only after contracts publish succeeds)
 
+## 3b) Publish via git tag (recommended for traceability)
+
+This repository supports tag-triggered publish with a single synchronized tag:
+
+- tag format: `vX.Y.Z`
+- both packages must use the same version `X.Y.Z`
+
+When a tag like `v0.2.0` is pushed:
+
+- workflow `phase1-ci-and-release` triggers on the tag,
+- release order remains enforced,
+- `scripts/validate_release_tag.py` verifies:
+  - `predicate_contracts/pyproject.toml` version == `predicate_authority/pyproject.toml` version,
+  - tag version matches both package versions.
+
+Example:
+
+```bash
+make tag-release VERSION=0.1.0
+git push origin v0.1.0
+```
+
 ## 4) Verify published artifacts
 
 ```bash
@@ -60,23 +82,14 @@ print("ok", predicate_contracts.__name__, predicate_authority.__name__)
 PY
 ```
 
-## 5) Optional: create git tags per package release
-
-Tags are not required for publishing in this repo, but they are recommended for traceability.
+## 5) Optional: manual tags (legacy style)
 
-Suggested tag format:
+If you need package-specific traceability tags for historical reasons, you can still add:
 
 - `predicate-contracts-vX.Y.Z`
 - `predicate-authority-vX.Y.Z`
 
-Example commands (after publish succeeds):
-
-```bash
-git tag -a predicate-contracts-v0.1.0 -m "predicate-contracts v0.1.0"
-git tag -a predicate-authority-v0.1.0 -m "predicate-authority v0.1.0"
-git push origin predicate-contracts-v0.1.0
-git push origin predicate-authority-v0.1.0
-```
+These tags are informational only; automated publish is wired to `vX.Y.Z`.
 
 ## 6) Manual fallback publish (if needed)
 

predicate_authority/README.md

@@ -1,6 +1,10 @@
 # predicate-authority
 
-`predicate-authority` provides pre-execution authorization for AI agent actions.
+`predicate-authority` is a deterministic pre-execution authority layer for AI agents.
+It binds identity, policy, and runtime evidence so risky actions are authorized
+before execution and denied fail-closed when checks do not pass.
+
+Docs: https://www.PredicateSystems.ai/docs
 
 Core pieces:
 

predicate_authority/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "predicate-authority"
 version = "0.1.0"
-description = "Pre-execution authority enforcement runtime for AI agents."
+description = "Deterministic pre-execution authority layer for AI agents."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT OR Apache-2.0"
@@ -27,6 +27,9 @@ predicate-authorityd = "predicate_authority.daemon:main"
 [project.optional-dependencies]
 telemetry = ["opentelemetry-api>=1.24.0"]
 
+[project.urls]
+Documentation = "https://www.PredicateSystems.ai/docs"
+
 [tool.setuptools]
 packages = ["predicate_authority", "predicate_authority.integrations"]
 

scripts/validate_release_tag.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _read_version(pyproject_path: Path) -> str:
+    content = pyproject_path.read_text(encoding="utf-8")
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if line.startswith("version = "):
+            value = line.split("=", maxsplit=1)[1].strip().strip('"')
+            if value:
+                return value
+    raise RuntimeError(f"Unable to read version from {pyproject_path}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate git release tag against package versions."
+    )
+    parser.add_argument(
+        "--tag",
+        required=True,
+        help="Git tag name, expected format vX.Y.Z",
+    )
+    args = parser.parse_args()
+    tag = args.tag.strip()
+    if not tag.startswith("v"):
+        raise SystemExit("Release tag must start with 'v' (example: v0.1.0)")
+    tag_version = tag[1:]
+    if tag_version == "":
+        raise SystemExit("Release tag version cannot be empty")
+
+    repo_root = Path(__file__).resolve().parents[1]
+    contracts_version = _read_version(repo_root / "predicate_contracts" / "pyproject.toml")
+    authority_version = _read_version(repo_root / "predicate_authority" / "pyproject.toml")
+
+    if contracts_version != authority_version:
+        raise SystemExit(
+            "Package versions are not in sync: "
+            f"predicate-contracts={contracts_version}, predicate-authority={authority_version}"
+        )
+    if tag_version != contracts_version:
+        raise SystemExit(
+            f"Tag version {tag_version} does not match package version {contracts_version}"
+        )
+
+    print(
+        "release tag validated:",
+        f"tag={tag}",
+        f"predicate-contracts={contracts_version}",
+        f"predicate-authority={authority_version}",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())