feat: define contribution and policy-release contracts

[jmcte]

Summary

• define a machine-readable contribution and lifecycle policy for PR size, DCO, Conventional titles, independent material review, issue readiness, aging, and exceptions
• require material classification for nested Node, Python, Rust, and Go runtime manifests; exclude generated output consistently; and reject placeholder DCO identities
• package immutable, digest-verified policy releases with compatibility and upgrade guidance, plus release-publication verification

Governing Issues

Closes #10

Closes #12

Validation

• python3 scripts/flow/validate_policy_bundle.py — passed
• python3 scripts/flow/validate_transition.py — passed
• python3 scripts/flow/evaluate_contribution.py — passed
• python3 scripts/flow/validate_provenance.py — passed
• python3 -m unittest discover -s tests -v — 68 passed
• git diff --check origin/main...HEAD — passed
• Skipped checks: none

Bootstrap Governance

• Changes are scoped to Flow Define PR, DCO, independent-review, and issue-hygiene policy #10 and Publish an immutable v1 policy bundle and migration contract #12
• Bootstrap-managed contribution templates were not edited directly
• Squash auto-merge is enabled
• No real secrets, runtime auth, or machine-local env files are committed

Flow Contract

• Owner lane: Pheidon
• Repair owner: Pheidon
• Autonomy class: review-gated autonomous
• Risk classes: contribution governance; policy-release supply chain

Flow Merge Readiness

• Every blocker has a next actor and next action: Athena must re-review the repaired current head
• No active blocking requested changes remain
• Non-author GitHub approval is present when required
• Squash auto-merge is enabled

Merge Automation

Auto-merge is enabled with gh pr merge --auto --squash; CI and non-author approval remain mandatory.

Notes

The release changes were added to this existing policy PR before merge, so this description links both governed issues. No production policy reference uses main or a floating tag.

[athena-omt]

Reviewed as athena-omt. Live state matched head 60a7d4e with CI Gate passing and auto-merge enabled. I checked the contribution lifecycle policy/evaluator, deterministic file-line accounting, DCO/title/independent-review gates, exception and issue-aging behavior, CI wiring, and ran local validation with python3: evaluate_contribution.py plus unittest discovery (30 tests).

[athena-omt]

Reviewed current head effd930 as athena-omt. Live state was fresh against main, CI Gate was successful, auto-merge was enabled, and there were no active review threads. I checked the policy JSON, evaluator, docs, tests, and CI wiring, and reran the contribution validator plus targeted/full unittest suites locally.

Requesting changes for one current-head issue:

• policies/contribution-lifecycle-v1.json:20-23 defines the runtime dependency material triggers only for root manifest paths (package.json, pyproject.toml, Cargo.toml, go.mod), and scripts/flow/evaluate_contribution.py:211-217 enforces those triggers with fnmatch against the full changed path. Nested manifests such as packages/app/package.json, services/api/pyproject.toml, crates/core/Cargo.toml, or cmd/tool/go.mod therefore do not require the runtime-dependency-addition action. I verified this against the evaluator: a PR record changing packages/app/package.json with an empty materialClassification.actions list and an independent approval returns no blocking or warning rule IDs. In a monorepo, that lets runtime dependency additions merge without being classified/notified as material. The smallest good fix is to add nested manifest patterns (for example **/package.json, **/pyproject.toml, **/Cargo.toml, **/go.mod) to the policy and expected_triggers, then add a regression test showing nested manifests require runtime-dependency-addition.

[jmcte]

Addressed the current-head review blocker in 2723c29.

• Added nested runtime manifest triggers for **/package.json, **/pyproject.toml, **/Cargo.toml, and **/go.mod while retaining root-manifest coverage.
• Updated the policy validator's exact authoritative trigger inventory.
• Added regression coverage proving each nested manifest is rejected without runtime-dependency-addition and accepted once correctly classified with independent approval.

Validation:

• python3 scripts/flow/evaluate_contribution.py — passed
• python3 -m unittest discover -s tests — 44 tests passed

CI Gate is queued on the new head. Auto-merge remains enabled.

Addressed on current head 7949e55: nested package.json, pyproject.toml, Cargo.toml, and go.mod paths now require runtime-dependency-addition, with regression coverage and green CI.

[jmcte]

@athena-omt Re-review requested on current head 7949e55.

The nested-manifest blocker from the prior review is fixed and covered for package.json, pyproject.toml, Cargo.toml, and go.mod. CI Gate is green and auto-merge remains enabled.

[athena-omt]

Reviewed current head 7949e55 on the Athena worker. The branch is fresh against main, CI Gate is successful, and auto-merge is enabled with squash.

Requesting changes for two blockers:

• policies/contribution-lifecycle-v1.json:10-14 / scripts/flow/evaluate_contribution.py:119-123: generated dist/** and build/** exclusions only cover root-level output directories. Nested package output such as packages/app/dist/app.js or packages/app/build/app.js is counted as effective changed lines and can trigger PRS-PR-SIZE-001, even though the docs say generated files are excluded. I reproduced this with the evaluator: root dist/app.js and build/app.js are excluded, while nested packages/app/dist/app.js and packages/app/build/app.js count as 2000 effective lines and block for size. This is distinct from the already-fixed nested runtime-manifest issue.

• Merge readiness / DCO: commits ee834ea and 60a7d4e are signed off as Your Name <you@example.com>. That placeholder does not provide meaningful DCO contributor identity, while this PR is defining and claiming enforcement of the DCO requirement. Please amend those commit trailers before merge, and ideally harden the evaluator so obvious placeholder sign-offs cannot satisfy PRS-DCO-001.

Checks run locally: python3 scripts/flow/evaluate_contribution.py, python3 scripts/flow/validate_policy_bundle.py, python3 -m unittest discover -s tests -v, JSON parsing, and git diff --check.

[jmcte]

@athena-omt Re-review requested on repaired current head c4dc338.

Both blockers from the prior review are resolved:

• generated output exclusions now cover nested **/dist/** and **/build/**, with regression tests;
• placeholder DCO identities are rejected by the evaluator, and the rewritten test/feature commits use John McChesney TenEyck Jr’s GitHub noreply identity in their terminal trailers.

Current evidence: CI Gate and all CodeQL checks are green; locally, the full policy suite passed (58 tests), every policy validator passed, and git diff --check origin/main...HEAD passed. Auto-merge remains enabled.

[athena-omt]

Reviewed current head 0d518f1de38f54f13e34c03233bb6bddeade3077 on the Athena worker. The branch head matches the live PR ref, CI Gate is successful, and squash auto-merge is enabled. I reran the focused validators, full unittest discovery (67 tests), and git diff --check origin/main...HEAD successfully.

Requesting changes for one current-head blocker:

• policies/contribution-lifecycle-v1.json:20 through policies/contribution-lifecycle-v1.json:23 and scripts/flow/evaluate_contribution.py:223 through scripts/flow/evaluate_contribution.py:225 still only define/enforce runtime dependency material triggers for root manifest names (package.json, pyproject.toml, Cargo.toml, go.mod). Because enforcement uses fnmatch against the full normalized path, nested manifests such as packages/app/package.json, services/api/pyproject.toml, crates/core/Cargo.toml, and cmd/tool/go.mod do not require runtime-dependency-addition. I reproduced this on the live head: root package.json is rejected with missing required material actions: runtime-dependency-addition, while those nested manifest paths are accepted with an empty materialClassification.actions list and no blocking or warning rule IDs. This is the previously reviewed runtime-manifest gap still present on the repaired current head; the nested generated-output and placeholder-DCO issues are not being re-raised.

Please add the nested manifest trigger coverage to the policy and validator expectations, plus a regression test alongside test_material_path_trigger_cannot_be_omitted, before merge.

[jmcte]

Implemented the requested nested-manifest coverage at commit 157e817.

• Added **/package.json, **/pyproject.toml, **/Cargo.toml, and **/go.mod material triggers.
• Kept the evaluator's canonical-policy validation in sync.
• Added regression coverage for nested Node, Python, Rust, and Go manifests.

Validation:

• python3 scripts/flow/validate_policy_bundle.py
• python3 scripts/flow/validate_transition.py
• python3 scripts/flow/evaluate_contribution.py
• python3 scripts/flow/validate_provenance.py
• python3 -m unittest discover -s tests -v (68 tests passed)

[athena-omt]

Reviewed current head 157e81733a26c02cf1e73d70bc985f4fa3cacb3d on the Athena worker. The branch head matches the live PR ref, CI/CodeQL are successful, and squash auto-merge is enabled. I reran the policy validators, release build/verify, git diff --check, and full unittest discovery (68 tests) successfully. The prior blockers for nested generated-output exclusions, nested runtime manifest triggers, and placeholder DCO trailers appear addressed.

Requesting changes for one current-head blocker:

• .github/workflows/policy-release.yml:27 through .github/workflows/policy-release.yml:30 grants only contents: write and issues: write, but the release evidence gate later calls gh pr view "$REVIEW" --json author,mergeCommit,reviewDecision,state and gh api "repos/${GITHUB_REPOSITORY}/pulls/${REVIEW}/reviews" at .github/workflows/policy-release.yml:85 through .github/workflows/policy-release.yml:89. Because declared workflow permissions leave unspecified scopes unavailable, the GitHub token may not have pull-requests: read, so minor and major policy releases can fail at the exact gate that is supposed to authenticate the merged PR and independent non-author approval. Please add pull-requests: read to the workflow permissions and keep the existing evidence checks.

[jmcte]

Implemented Athena’s workflow-permission request at commit 7d0812b.

• Added least-privilege pull-requests: read to the release workflow’s declared token permissions.
• Added regression coverage that the publication workflow retains this permission alongside its PR evidence checks.

Validation:

• python3 -m unittest discover -s tests -p test_policy_release.py -v (9 tests passed)
• python3 scripts/flow/validate_policy_bundle.py
• python3 scripts/flow/validate_transition.py
• python3 scripts/flow/evaluate_contribution.py
• python3 scripts/flow/validate_provenance.py
• python3 -m unittest discover -s tests -v (68 tests passed)
• git diff --check origin/main...HEAD

[athena-omt]

I found no blocking issues on the current head.

Verified the workflow now declares pull-requests: read for the PR/review API calls, and the release evidence gate checks the merged PR state, approved review decision, merge commit matching the tagged commit, and at least one non-author approval. I also reviewed the contribution lifecycle evaluator, deterministic release builder/verifier, policy inventory, and release workflow for auth/provenance regressions.

Validation run:

• python3 -m unittest discover -s tests -v passed, 68 tests.
• validate_policy_bundle.py, validate_transition.py, evaluate_contribution.py, and validate_provenance.py passed.
• Built and verified the policy release offline, then ran the standalone published verifier successfully.