From 44678fffc8ed626e2c218e689c5bc5c1508c60a2 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 11:31:44 +0900 Subject: [PATCH 01/12] docs(agents): avoid no-op pull request lifecycle runs Signed-off-by: Seongho Bae --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index abc12d0221..312de497ba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,12 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- - Put concurrency at workflow scope when queued jobs must be coalesced before a runner is admitted. Job-level concurrency cannot relieve a saturated runner queue because it is evaluated only after job admission. +- Subscribe only to pull-request actions that can produce useful work. The + default review set is `opened`, `synchronize`, `reopened`, and + `ready_for_review`; do not add `converted_to_draft` or `closed` merely to run + a job-level false condition, because the workflow run still enters the + organization queue. Add a lifecycle action only when that workflow performs + an explicit, tested cleanup or state transition for it. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, polling `sleep`, or another scheduled scan to compensate for incorrect concurrency. Cancel only runs proven to belong to a From 6771febb5d4e39bdfb4cc48926097bc8a4db9bdb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 12:00:20 +0900 Subject: [PATCH 02/12] docs(agents): preserve unchanged-head evidence Signed-off-by: Seongho Bae --- AGENTS.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 312de497ba..aeecdd9a92 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,10 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- `ready_for_review`; do not add `converted_to_draft` or `closed` merely to run a job-level false condition, because the workflow run still enters the organization queue. Add a lifecycle action only when that workflow performs - an explicit, tested cleanup or state transition for it. + an explicit, tested cleanup or state transition for it. That cleanup must + compare the live PR head and cancel only runs bound to a different head; + putting an unchanged-head draft or close event into the same PR concurrency + group would cancel current evidence rather than a superseded head. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, polling `sleep`, or another scheduled scan to compensate for incorrect concurrency. Cancel only runs proven to belong to a From 51efc5f2e34e7402aac03a67970c6970e707609f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 12:01:03 +0900 Subject: [PATCH 03/12] docs(agents): isolate stale workflow reruns Signed-off-by: Seongho Bae --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index aeecdd9a92..dd5ac343eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,10 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- target repository, and pull request number with `cancel-in-progress: true`; do not include the head SHA, because that prevents a new head from cancelling its predecessor. Non-PR triggers need an explicit collision-safe fallback. +- Do not let a rerun of an older run ID re-enter the live PR group and cancel + newer evidence. Use the PR number only for the first attempt and fall back to + `github.run_id` for reruns, or reject the rerun through exact-live-head + admission before it can displace current work. - Put concurrency at workflow scope when queued jobs must be coalesced before a runner is admitted. Job-level concurrency cannot relieve a saturated runner queue because it is evaluated only after job admission. From 1a416850f0017ef0907a943bf8c9ba6d26384105 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 12:20:10 +0900 Subject: [PATCH 04/12] docs(agents): isolate lifecycle cleanup groups --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index dd5ac343eb..b1889e5181 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,8 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- compare the live PR head and cancel only runs bound to a different head; putting an unchanged-head draft or close event into the same PR concurrency group would cancel current evidence rather than a superseded head. + Put such lifecycle cleanup in a separate, lifecycle-specific concurrency + group that cannot cancel or replace the PR-number evidence group. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, polling `sleep`, or another scheduled scan to compensate for incorrect concurrency. Cancel only runs proven to belong to a From ecdbce0492e9b47d85800d2c34480c93b7efa2a4 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 12:20:36 +0900 Subject: [PATCH 05/12] docs(agents): verify asynchronous run cancellation --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b1889e5181..fdccfd0079 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,7 +64,8 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- organization-wide queue sweep, polling `sleep`, or another scheduled scan to compensate for incorrect concurrency. Cancel only runs proven to belong to a superseded head of the same PR, then verify each accepted cancellation - reaches `completed/cancelled`. + reaches `completed/cancelled` by polling `actions/runs/{run_id}` with a + bounded retry; an HTTP 202 from cancel or force-cancel is not completion. - Classify a run's PR head by event-specific evidence before cancellation. `pull_request` may use the run's top-level `head_sha`, but `pull_request_target` records the trusted base there; use its PR association From b97eeed77aa8c7aa277973e11013a71bc81353df Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 13:21:40 +0900 Subject: [PATCH 06/12] docs(agents): clarify lifecycle cancellation groups --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fdccfd0079..a2315c6d3e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,12 +54,12 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- `ready_for_review`; do not add `converted_to_draft` or `closed` merely to run a job-level false condition, because the workflow run still enters the organization queue. Add a lifecycle action only when that workflow performs - an explicit, tested cleanup or state transition for it. That cleanup must - compare the live PR head and cancel only runs bound to a different head; - putting an unchanged-head draft or close event into the same PR concurrency - group would cancel current evidence rather than a superseded head. - Put such lifecycle cleanup in a separate, lifecycle-specific concurrency - group that cannot cancel or replace the PR-number evidence group. + an explicit, tested cleanup or state transition for it. A draft or close + event whose purpose is to retire active evidence for that PR must share the + PR evidence concurrency group and publish the required exempt/terminal state. + An auxiliary cleanup that scans and cancels runs by API must instead use a + lifecycle-specific group so it cannot preempt current-head evidence; compare + the live PR state and head immediately before every cancellation. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, polling `sleep`, or another scheduled scan to compensate for incorrect concurrency. Cancel only runs proven to belong to a From 1ba1e39ff2c6f49e7aefa7c435692ffc45331a75 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 13:44:22 +0900 Subject: [PATCH 07/12] docs(agents): tighten cancellation verification --- AGENTS.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a2315c6d3e..794e205249 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,13 +59,17 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- PR evidence concurrency group and publish the required exempt/terminal state. An auxiliary cleanup that scans and cancels runs by API must instead use a lifecycle-specific group so it cannot preempt current-head evidence; compare - the live PR state and head immediately before every cancellation. + the live PR state and head immediately before every cancellation. After a + cancellation reaches its terminal state, re-read both the PR and target run; + if the cancelled run now matches the live head, enqueue replacement evidence + instead of treating cleanup as successful. - Keep cleanup repository-local and event-driven. Do not restore an - organization-wide queue sweep, polling `sleep`, or another scheduled scan to - compensate for incorrect concurrency. Cancel only runs proven to belong to a - superseded head of the same PR, then verify each accepted cancellation - reaches `completed/cancelled` by polling `actions/runs/{run_id}` with a - bounded retry; an HTTP 202 from cancel or force-cancel is not completion. + organization-wide queue sweep, unbounded sleep-based polling, or another + scheduled scan to compensate for incorrect concurrency. Cancel only runs + proven to belong to a superseded head of the same PR, then poll + `actions/runs/{run_id}` with a bounded retry. Treat cancellation as complete + only when `status == "completed"` and `conclusion == "cancelled"`; an HTTP + 202 from cancel or force-cancel is not completion. - Classify a run's PR head by event-specific evidence before cancellation. `pull_request` may use the run's top-level `head_sha`, but `pull_request_target` records the trusted base there; use its PR association From ae64bf388d6a119620b686e6593658d9789832f7 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 14:35:33 +0900 Subject: [PATCH 08/12] docs(agents): guard replacement evidence enqueue Signed-off-by: Seongho Bae --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 794e205249..628b22a67b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,7 +61,9 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- lifecycle-specific group so it cannot preempt current-head evidence; compare the live PR state and head immediately before every cancellation. After a cancellation reaches its terminal state, re-read both the PR and target run; - if the cancelled run now matches the live head, enqueue replacement evidence + only if the PR is still open and non-draft and the cancelled target still + matches its live head, enqueue at most one replacement keyed by PR, workflow, + and target head. Revalidate that exact head again during replacement admission instead of treating cleanup as successful. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, unbounded sleep-based polling, or another From b4934b7c201d90c614c27493ace22c0634791b1a Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 15:24:38 +0900 Subject: [PATCH 09/12] =?UTF-8?q?docs(agents):=20=EC=8A=A4=ED=82=AC=20?= =?UTF-8?q?=EC=84=A0=ED=83=9D=EA=B3=BC=20=EA=B2=80=EC=A6=9D=C2=B7=EC=9D=B8?= =?UTF-8?q?=EA=B3=84=20=EC=A0=88=EC=B0=A8=20=EB=B3=B4=EA=B0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 628b22a67b..f06e6f04af 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,35 @@ false claim of explicit owner direction and records the resulting availability risk as open and unreviewed, not accepted. The materialization contract is also covered by [`docs/doctoring/exact-artifact-sbom-attestation.md`](docs/doctoring/exact-artifact-sbom-attestation.md). +## Skills, root-cause fixes, and handoff + +- Read the installed `SKILL.md` before using a skill; choose it for the task, + not merely because it is installed. Apply Ponytail after tracing the affected + callers: reuse the canonical owner, existing code, standard library, native + platform, and installed dependencies before adding an implementation. +- Use Superpowers `systematic-debugging` for failures, `test-driven-development` + for behavior changes, and `verification-before-completion` for delivery + claims. Reproduce the failure, fix its shared cause, and run the regression + check. Never claim RED was observed unless the pre-fix check actually failed. + Use `autoresearch` only for a bounded experiment with a baseline, measurable + metric, and result log; documentation-only edits need no experiment scaffold. +- Use CodeGraph in the exact worktree being changed; initialize a missing index + and sync an unhealthy index. Use Context7 for external library/API contracts + and DeepWiki for repository context, then verify against current source and + official documentation. Report unavailable tools or stale indexes explicitly. + Apply `humanize-korean`/`im-not-ai` to Korean prose without changing facts; + use `adr-author` when recording an architectural decision. +- Confirm repository, worktree, branch, dirty files, and live PR head/base before + editing. Preserve other agents' changes; coordinate one writer per shared + delta and use isolated worktrees for independent changes. Fix owner defects + there and consume released contracts, not copied source or temporary branches. +- Keep progress in the existing Project/PR, not a competing private tracker. + Handoffs include owner, worktree, PR URL, head/base SHA, commands and results, + unresolved findings, and the next safe action. Count only verified acceptance + items in progress percentages and state the denominator. Local tests, protected + merge, and live operation are separate milestones; queued checks, enabled + auto-merge, and a lost test-session handle prove none of them. + ## Actions queue and protected-merge procedure - Use `github-actions-privileged-pr-scan` when a PR scanner can reach secrets, @@ -43,12 +72,16 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- do not include the head SHA, because that prevents a new head from cancelling its predecessor. Non-PR triggers need an explicit collision-safe fallback. - Do not let a rerun of an older run ID re-enter the live PR group and cancel - newer evidence. Use the PR number only for the first attempt and fall back to - `github.run_id` for reruns, or reject the rerun through exact-live-head - admission before it can displace current work. -- Put concurrency at workflow scope when queued jobs must be coalesced before a - runner is admitted. Job-level concurrency cannot relieve a saturated runner - queue because it is evaluated only after job admission. + newer evidence. Use the PR number only when `github.run_attempt == 1`; + isolate reruns with a `rerun-` prefix and `github.run_id`. Retain exact-live-head + admission before privileged work and evidence publication. An admission job + cannot undo a cancellation already caused by workflow-level concurrency. +- Put concurrency at workflow scope to coalesce whole runs, including their + bootstrap jobs. Job-level concurrency controls only the jobs carrying that + setting; do not infer a runner-admission ordering guarantee. See GitHub's + [workflow and job concurrency contract](https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency). + Keep release, publish, deploy, and migration work outside cancellable PR + evidence groups; preserve their serialization and idempotency safeguards. - Subscribe only to pull-request actions that can produce useful work. The default review set is `opened`, `synchronize`, `reopened`, and `ready_for_review`; do not add `converted_to_draft` or `closed` merely to run From 972d87e35eec625e7d37d69cd2d9b17fce5e75fb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 15:26:40 +0900 Subject: [PATCH 10/12] =?UTF-8?q?docs(agents):=20=EC=9A=B4=EC=98=81=20?= =?UTF-8?q?=EC=A7=80=EC=B9=A8=EA=B3=BC=20=EC=8B=A4=EC=A0=9C=20=EA=B2=80?= =?UTF-8?q?=EC=A6=9D=20=EC=83=81=ED=83=9C=20=EA=B5=AC=EB=B6=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f06e6f04af..9d320051b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,6 +63,11 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- ## Actions queue and protected-merge procedure +These are required operating rules, not evidence that every current workflow +implements them. Check the exact workflow revision and its regression/live-run +evidence; record any gap in the owning PR instead of claiming a docs-only fix +changed runtime behavior. + - Use `github-actions-privileged-pr-scan` when a PR scanner can reach secrets, and use `github-robot-review-gate` plus `babysit-pr` when diagnosing or monitoring a protected PR. If a named skill is unavailable, preserve its @@ -100,7 +105,8 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- instead of treating cleanup as successful. - Keep cleanup repository-local and event-driven. Do not restore an organization-wide queue sweep, unbounded sleep-based polling, or another - scheduled scan to compensate for incorrect concurrency. Cancel only runs + scheduled scan to compensate for incorrect concurrency. For superseded-head + cleanup, cancel only runs proven to belong to a superseded head of the same PR, then poll `actions/runs/{run_id}` with a bounded retry. Treat cancellation as complete only when `status == "completed"` and `conclusion == "cancelled"`; an HTTP @@ -112,11 +118,18 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- also executes on the control-plane branch, so bind it to the validated target repository, PR number, and target-head SHA from its payload or run name. Never compare either event's top-level `head_sha` directly with the live PR - head. If a current-head dispatch is cancelled while deduplicating, enqueue - exactly one replacement for that PR and workflow and verify the replacement - carries the same live target head. + head. Same-head duplicate coalescing and inactive-PR cleanup need their own + eligibility checks; neither is evidence of a superseded head. If current-head + evidence is accidentally cancelled, use the replacement eligibility and + deduplication rules above; never cancel healthy current-head evidence merely + to force a replacement. - Before every review, retry, push, or merge claim, re-fetch the PR's exact head SHA, base SHA, review threads, required checks, and ruleset result. A push invalidates earlier checks and reviews. Never self-approve, dismiss reviews, force-push, disable a security gate, or use admin bypass for product or security changes. +- Queue pressure alone grants no bypass authority. An explicitly user-authorized + Actions bootstrap exception must identify the exact diff and the causal gate + it repairs, preserve independent exact-head review and unaffected gates, and + record post-merge verification. Never extend that exception to unrelated PRs + or treat the bypass itself as passing protected-gate evidence. From a8e2a5f98567ec17ddb9c9ca42a31d539508dbba Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 16:10:27 +0900 Subject: [PATCH 11/12] =?UTF-8?q?docs(agents):=20=EC=8B=A4=ED=96=89=20revi?= =?UTF-8?q?sion=EA=B3=BC=20PR=20=EC=97=B0=EA=B2=B0=20=EC=A0=95=EB=B3=B4=20?= =?UTF-8?q?=ED=8C=90=EC=A0=95=EC=9D=84=20=EA=B5=AC=EB=B6=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9d320051b3..bbf470e759 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -112,13 +112,25 @@ changed runtime behavior. only when `status == "completed"` and `conclusion == "cancelled"`; an HTTP 202 from cancel or force-cancel is not completion. - Classify a run's PR head by event-specific evidence before cancellation. - `pull_request` may use the run's top-level `head_sha`, but - `pull_request_target` records the trusted base there; use its PR association - and immutable run name/event payload instead. A `repository_dispatch` run - also executes on the control-plane branch, so bind it to the validated target + Do not confuse runtime `github.sha`/`GITHUB_SHA` with REST run `head_sha`. + Native and organization-required `pull_request_target` runs observed here + retain the original PR head in REST `head_sha`, while their + `pull_requests[].head.sha` association can refresh after another push. + A current PR association alone cannot prove an old run checks the current + revision. Bind the recorded run revision to the repository/PR identity and + revalidate the live PR before cancellation; preserve runs whose identity + cannot be proven. In the 2026-09-05 REST observation, + [CO run 33949656057](https://github.com/ContextualWisdomLab/contextual-orchestrator/actions/runs/33949656057) + retained revision `1481c595dc1d16e7bf4b65addaf0bd30322cf2b8` while its + association named `6d1b30803888e893d7bdbdf4d12605a16c36162d`. + Main `6d7fbebec8aec31d88a30a36e71ca5b3925d241d` still permits association-only + coalescer authority; [#1899](https://github.com/ContextualWisdomLab/.github/pull/1899) + tracks the proposed runtime correction. This procedure does not prove that + correction is deployed. A `repository_dispatch` run executes on the control-plane + branch, so bind it to the validated target repository, PR number, and target-head SHA from its payload or run name. - Never compare either event's top-level `head_sha` directly with the live PR - head. Same-head duplicate coalescing and inactive-PR cleanup need their own + Do not use a dispatch run's top-level `head_sha` as its target PR head. + Same-head duplicate coalescing and inactive-PR cleanup need their own eligibility checks; neither is evidence of a superseded head. If current-head evidence is accidentally cancelled, use the replacement eligibility and deduplication rules above; never cancel healthy current-head evidence merely From 2b8db866f58c04648359cf70869f8c8f48bffddc Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 5 Sep 2026 17:03:36 +0900 Subject: [PATCH 12/12] =?UTF-8?q?docs(agents):=20=EC=9D=BD=EA=B8=B0=20?= =?UTF-8?q?=EC=A0=84=EC=9A=A9=20=EA=B2=80=ED=86=A0=EC=9D=98=20=EC=9D=B8?= =?UTF-8?q?=EB=8D=B1=EC=8A=A4=20=EB=B3=80=EA=B2=BD=20=EA=B8=88=EC=A7=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index bbf470e759..59298b82d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,7 +45,9 @@ The materialization contract is also covered by [`docs/doctoring/exact-artifact- Use `autoresearch` only for a bounded experiment with a baseline, measurable metric, and result log; documentation-only edits need no experiment scaffold. - Use CodeGraph in the exact worktree being changed; initialize a missing index - and sync an unhealthy index. Use Context7 for external library/API contracts + and sync an unhealthy index. An explicitly read-only scope takes precedence: + do not initialize or sync there; report a missing or stale index and use + focused source inspection instead. Use Context7 for external library/API contracts and DeepWiki for repository context, then verify against current source and official documentation. Report unavailable tools or stale indexes explicitly. Apply `humanize-korean`/`im-not-ai` to Korean prose without changing facts;