Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/a38-guard.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ For each reviewer, the latest substantive submitted state controls authorization

An authorized migration may introduce, remove or change workflows, and may also add, remove or change `.github/pr-guard.json`, but the complete current head inventory and author report still must satisfy the approved head policy. Proposed pr-guard configuration is never used for scope until it is merged to the trusted default-branch revision. The executable guard remains pinned and never runs head commands. The **base policy's enforcement mode stays active** for this PR, even if the proposed mode is `observe`. If no valid base policy exists, explicit approval permits bootstrap under `enforce`; initial adoption cannot silently bypass reporting.

Publish the migration proposal draft first per the [pull request lifecycle](pull-request-lifecycle.md). Measurement and verification against the still-active base policy may follow on that same signed commit; that run is proposal evidence, not Ready evidence. Once the exact current head/base approval exists, rerun the full approved head policy and local verification, publish that newly generated report, and perform the live join. Bootstrap with a missing or invalid base policy likewise publishes the draft first under the lifecycle (full pre-push test gates are not a draft blocker), then requires explicit approval and `enforce`; it must not invent a report or waive approval.
Publish the migration proposal draft first per the [pull request lifecycle](pull-request-lifecycle.md). Measurement and verification against the still-active base policy may follow on that same signed commit; that run is proposal evidence, not Ready evidence. Once the exact current head/base approval exists, apply the canonical [evidence reuse after approval](a38.md#evidence-reuse-after-approval) rules. An unchanged complete successful report can be revalidated and published with its original timestamps and results; approval alone does not require executing the tests again. A complete new run is required when the reuse conditions are not met. Always perform fresh local verification and the live join. Bootstrap with a missing or invalid base policy likewise publishes the draft first under the lifecycle (full pre-push test gates are not a draft blocker), then requires explicit approval and `enforce`; it must not invent a report or waive approval.

The bot identifies the active policy revision in its comment. Download `.github/a38.json` from that exact revision before generating the report. For ordinary PRs, this is the base; for explicitly approved migrations, it is the head.

Expand Down
18 changes: 16 additions & 2 deletions docs/a38.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,23 @@ The guard reads the A38 manifest at the PR's immutable base SHA. A report cannot

After that approval, the exact approved head manifest becomes the active policy data, but the executable guard remains pinned and the base policy's enforcement mode remains effective until merge. The full workflow inventory and report are then reassessed against the head policy. A new head or base invalidates the approval and requires a new exact approval and full reassessment.

For a new migration proposal, publish the draft first per the [pull request lifecycle](pull-request-lifecycle.md). Proposal measurement against the still-active base policy may follow that publication on the same signed commit; this proposal run is not Ready evidence. After exact approval, fetch the approved head policy and repeat the complete run, local verification, author publication, and live join against the current head policy. Do not use an unapproved head manifest as the active policy.
For a new migration proposal, publish the draft first per the [pull request lifecycle](pull-request-lifecycle.md). Proposal measurement against the still-active base policy may follow that publication on the same signed commit; this proposal run is not Ready evidence. After exact approval, fetch the approved head policy and apply [evidence reuse after approval](#evidence-reuse-after-approval): revalidate matching existing evidence instead of unconditionally executing the tests again. Do not use an unapproved head manifest as the active policy.

If the base manifest is missing or invalid, bootstrap requires the same independent explicit approval of the exact current head and base and is always `enforce`; absence is never a waiver. Publish the bootstrap proposal draft first per the [pull request lifecycle](pull-request-lifecycle.md); full pre-push test gates are not a draft-publication blocker. For review, the exact proposed head policy may be loaded outside the checkout and used to run the actual complete tests and produce a genuine author report, clearly marked as `PROPOSED` evidence; this does not activate the policy, substitute for approval, confer private A38 Ready equivalence before a valid base policy exists, or satisfy the final Ready live join. After approval, the original proposed report may qualify under [evidence reuse after approval](#evidence-reuse-after-approval); otherwise execute the complete required run against the now-active policy. In both cases, verify the report, publish it and perform the fresh live join. Never handcraft or fabricate a report. See the guard instructions for event handling and operational limits.

### Evidence reuse after approval

Approval changes authorization; it does not by itself invalidate a completed test run. A successful report measured before approval may become Ready evidence after approval when all of the following are proven:

- The target repository, exact tested head and base are unchanged.
- The saved policy used for measurement is byte-identical to the now-active approved policy, and its required job inventory, commands and timeouts still match the complete successful report.
- Relevant recorded execution inputs, including companion repository revisions, are unchanged. The saved policy and run provenance must be available; do not infer equivalence from a green summary alone.
- The exact current policy approval remains valid, and fresh local verification and the current live guard assessment both pass.

Revalidate the original report against the approved policy, publish it through the original author's account and perform the fresh live join. Preserve the original report block, measurement timestamp, results and durations; do not make an old run appear newly executed. This also applies to a bootstrap report originally marked `PROPOSED`, once its exact policy has actually been approved.

If required inputs changed, equivalence cannot be established, or evidence is missing, stale, incomplete or failed, execute the complete required suite again and generate a new report. Reuse never substitutes for approval, permits unapproved policy activation, or bypasses an independently required GitHub check or human merge.

If the base manifest is missing or invalid, bootstrap requires the same independent explicit approval of the exact current head and base and is always `enforce`; absence is never a waiver. Publish the bootstrap proposal draft first per the [pull request lifecycle](pull-request-lifecycle.md); full pre-push test gates are not a draft-publication blocker. For review, the exact proposed head policy may be loaded outside the checkout and used to run the actual complete tests and produce a genuine author report, clearly marked as `PROPOSED` evidence; this does not activate the policy, substitute for approval, confer private A38 Ready equivalence before a valid base policy exists, or satisfy the final Ready live join. After approval, repeat the complete measured run and author report against the now-active policy, perform the live join, and rerun whenever required; the evidence and current policy must match. Never handcraft or fabricate a report. See the guard instructions for event handling and operational limits.

## Adoption and CI boundaries

Expand Down
Loading