From 6f202858c26b06e033508f35ef9d63f1a5ce1042 Mon Sep 17 00:00:00 2001 From: CometAPI Date: Thu, 23 Jul 2026 15:14:54 +0800 Subject: [PATCH] docs: harden cold-start lifecycle --- AGENTS.md | 29 +++++++++++++++++------------ RELEASING.md | 31 +++++++++++++++++++++++++++++++ ROADMAP.md | 4 ---- 3 files changed, 48 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e5f177b..4cad57a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,15 +25,20 @@ proves only its own evidence layer. Never invent or mock missing evidence. checks pass and its squash merge is present on `origin/main`. Any alternate disposition requires explicit user authorization and must not advance `dev` until the accepted commit is present on `origin/main`. -- With a clean worktree, fetch `origin`, switch to `main`, fast-forward it with - `git merge --ff-only origin/main`, switch to `dev`, fast-forward it with - `git merge --ff-only main`, and finish with `dev` checked out. Cleanup is - complete only when the worktree is clean and local `main`, local `dev`, and - `origin/main` resolve to the same commit. -- Never reset, discard work, force-update refs, delete branches, or push `dev` - merely to complete this cleanup. If fetching fails, the worktree is dirty, - either fast-forward is impossible, or the three final refs differ, stop and - report the exact state instead of forcing synchronization. +- With a clean worktree, fetch `origin`, switch to `main`, and fast-forward it + with `git merge --ff-only origin/main`. Require the worktree to remain clean + and `main` to equal `origin/main` before handling `dev`. If local `dev` + exists, require it to be an ancestor of `main`, switch to it, and fast-forward + it with `git merge --ff-only main`; if it does not exist, create it with + `git switch -c dev` only from that checked-out, clean, synchronized `main`. + Finish with `dev` checked out. Cleanup is complete only when the worktree is + clean and `HEAD`, local `main`, local `dev`, and `origin/main` resolve to the + same commit. +- Never reset, discard work, force-update refs, delete branches, or push `dev`. + If fetching fails, the worktree is dirty, `main` cannot fast-forward to + `origin/main`, an existing `dev` cannot fast-forward to `main`, or the four + final refs differ, stop and report the exact state instead of forcing + synchronization. ## Current milestone: Public Preview @@ -58,9 +63,9 @@ The accepted identity is: Before changing repository visibility: -1. Resolve or explicitly defer every open dependency pull request that is not - ready to merge. Dependabot PR #2 must not merge while its credential-free CI - is failing; record its disposition in `ROADMAP.md`. +1. Resolve or explicitly defer every dependency disposition that `ROADMAP.md` + still records as unresolved; its pre-visibility dependency disposition table + is the durable source of truth. 2. Keep `.github/CODEOWNERS` absent until a real multi-maintainer model exists. 3. Keep scheduled and manually dispatched live smoke fail-closed behind `LIVE_SMOKE_ENABLED=true`, and keep `RELEASE_PLEASE_ENABLED` disabled through diff --git a/RELEASING.md b/RELEASING.md index 8c5f390..da804da 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -90,6 +90,37 @@ and an offline mocked call. Record every command, outcome, skipped check, and unavailable tool in the verification record. +## Final post-merge evidence + +After a pre-visibility pull request is squash-merged, complete its evidence +record against the resulting default-branch commit: + +1. Fetch `origin`, obtain the pull request's squash-merge SHA, verify that it is + an ancestor of `origin/main`, and capture the current `origin/main` commit as + the final `main` SHA. +2. Wait for the credential-free default-branch `CI` run for that final `main` + SHA and require every blocking job to pass. Record the run URL; pull-request + CI is not a substitute for this post-merge run. +3. Perform a read-only authorization-boundary audit. Record the repository's + observed current visibility and other relevant observable state separately + from the lifecycle attestation that this workflow made no visibility, + settings, rules, secrets, or environments mutation and performed no live API, + tag, release, or PyPI operation. Do not treat state hidden by permissions as + affirmative evidence. +4. Follow the `AGENTS.md` branch lifecycle using only fast-forward updates, then + require a clean worktree on `dev` with `HEAD`, local `main`, local `dev`, and + `origin/main` equal to the final `main` SHA. Never push `dev`. +5. Add a timeline comment to the merged pull request containing its squash-merge + SHA, the verified ancestry from that commit to the final `main` SHA, the final + `main` SHA, default-branch CI result and URL, observed boundary-audit state, + lifecycle attestation, and local worktree and ref state. Use that comment as + the durable final evidence record and retain its URL. + +If any required evidence fails or is unavailable, stop and report the exact +state instead of claiming completion. A commit cannot truthfully record its own +future squash-merge SHA, post-merge CI, or final comment URL; do not create +another commit to chase that circular record. + ## Workflow validation The repository wrapper pins `actionlint` 1.7.12 and verifies the release diff --git a/ROADMAP.md b/ROADMAP.md index b38e0eb..be265a1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -231,10 +231,6 @@ Failed or unavailable checks: not replacement evidence for PR #9. An earlier intentional offline actionlint probe in a fresh detached worktree failed closed before the verified cache was populated; it is not final-candidate validation evidence. -- The execution environment rejected `rm -rf dist` before it ran, so no file was - removed. The final candidate instead used the newly created empty - `dist/previsibility-20260723` directory and completed the equivalent clean - build, inspection, and two-artifact install gates there. Remote evidence: