From 69acc2a31c3dfad453de8d66dd8d58e09d6045a2 Mon Sep 17 00:00:00 2001 From: CodeSigils Date: Wed, 23 Sep 2026 14:57:32 +0300 Subject: [PATCH] docs: record contract-monitor automation flow --- CONTRIBUTING.md | 16 ++++++++-------- README.md | 11 ++++++----- proposals/ROADMAP.md | 14 ++++++++++++++ 3 files changed, 28 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 130bd31..bcea894 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -68,15 +68,15 @@ safety. 2. Update `docs/evidence-urls.json` with the observed status and verification date; keep durable guidance in the relevant reference file. 3. Run the URL verifier and documentation checks. -4. If the scheduled monitor opens a drift PR, read its check counts and review - the diff for semantic changes. A timestamp refresh alone is not evidence - that a contract is still correct. -5. GitHub may require explicit approval before the workflow-authored PR's - required checks can run. Approve only after confirming the PR is - repository-owned and changes only the evidence manifest; this approval is - intentional and must not be weakened into a broad bypass. +4. If the scheduled monitor opens a drift PR, it is a canonical-URL correction + and carries the `needs:semantic-review` label. Read its check counts and + review the diff for semantic changes; a timestamp refresh alone is not + evidence that a contract is still correct. +5. Timestamp-only refreshes do not open a PR: the workflow merges them directly + with a signed squash commit, so no human step is required for them. 6. The monitor signs its commits to satisfy the protected branch's - signed-commit rule. Required checks must still pass before merge. + signed-commit rule; canonical-URL correction PRs are merged by a maintainer + after review. Never copy credentials, private URLs, or candidate secrets into evidence files, issues, or reports. diff --git a/README.md b/README.md index 6941cb0..72e549a 100644 --- a/README.md +++ b/README.md @@ -263,11 +263,12 @@ CI performs payload and documentation checks on pushes and pull requests. External URL monitoring runs on a schedule or manually so transient third-party outages do not make ordinary documentation changes flaky. The monitor uses bounded retries and response sizes, checks independent sources concurrently, -and opens a reviewable PR only for safe canonical-URL corrections or refreshed -verification evidence. Its PR body reports the number of contracts checked, -timestamp refreshes, and canonical URL corrections. Workflow-authored changes -remain reviewable and signed; required PR checks are intentionally relaxed -during solo evaluation. +and opens a reviewable PR only when a drift fix changes a canonical URL +(timestamp-only refreshes are merged directly). Its PR body reports the number +of contracts checked, timestamp refreshes, and canonical URL corrections. +Canonical-URL correction PRs carry the `needs:semantic-review` label and require +a maintainer merge; timestamp-only refreshes are merged by the workflow with a +signed squash commit. ### Catalog status diff --git a/proposals/ROADMAP.md b/proposals/ROADMAP.md index 5340656..5991ae4 100644 --- a/proposals/ROADMAP.md +++ b/proposals/ROADMAP.md @@ -340,6 +340,20 @@ installation implicitly mutating. ## Implementation record +### 2026-09-23 — Contract-monitor automation split + +Timestamp-only evidence refreshes (`last_verified` bumps) no longer open a +reviewable PR: the monitor workflow merges them directly with a signed squash +commit via `gh pr merge --squash --delete-branch`. Auto-merge (`--auto`) is +intentionally not used here — main has zero required status checks, so GitHub +declines enabling auto-merge on immediately-mergeable PRs ("Pull request is in +clean status (enablePullRequestAutoMerge)"). Canonical URL corrections still +open a review PR carrying the `needs:semantic-review` label and require a +maintainer merge. Main requires verified signatures (`required_signatures`), so +direct pushes are impossible and all changes land as GitHub-signed squash +merges. This resolves the stuck bot-PR loop seen with #102/#105 (open PRs never +merged; #105 closed as superseded). + ### 2026-09-15 — Skill payload budget review - Reviewed the `skill-budget` cron-health warning: `skills/skill-discovery/SKILL.md`