Repository navigation
docs(rules): codify workflow orchestration invariants and pin canonical release targets - #1006
Merged
Merged
Conversation
There was a problem hiding this comment.
Code Review
This pull request introduces a new section on workflow orchestration and remote automation invariants to the automation rules, emphasizing strict target commit pinning, asynchronous run correlation, and environment-aware state persistence. It also updates the release notes generation skill playbook to fetch remote tags, use canonical references (origin/main), and utilize the ARTIFACT_DIR environment variable for file paths. The review feedback suggests improving robustness by consolidating placeholders like <base_tag> and into shell variables at the top of their respective execution blocks to prevent manual substitution errors.
…al release targets - Add Section 9 to .agents/rules/skills_and_automation.md establishing strict target commit pinning, asynchronous polling correlation invariants, and no || true error suppression rules. - Update .agents/skills/xmc_generate_release_notes/SKILL.md to pin base tag discovery and release publishing to origin/main. TAG=agy CONV=85ef69c5-6bd6-4ccb-bac3-6d26ad135417
janzak-dev
force-pushed
the
docs/rules-workflow-orchestration-invariants
branch
from
September 28, 2026 14:20
9a6bfdf to
0f2fc50
Compare
8000
- Mandate non-mutating preflight validation (--dry-run) before mandatory confirmation gates. - Codify explicit prohibition against --force or autonomous tag overwrites. - Standardize multi-turn state resumption idiom using conditional parameter expansion and state files. - Mandate dedicated Python helpers for multi-step CI polling and JSON parsing. - Consolidate variable placeholders at top of playbook bash snippets. - Document draft-to-public release promotion ownership and dedicated confirmation gate in xmc_generate_release_notes. - Enforce structured error summarization and conclusion discrimination without raw log dumping. TAG=agy CONV=85ef69c5-6bd6-4ccb-bac3-6d26ad135417
…ection 9 - Expand Target Commit Pinning to cover verification and validation automation scripts. - Expand State Resumption and Persistence idiom to verification results and generated reports. TAG=agy CONV=85ef69c5-6bd6-4ccb-bac3-6d26ad135417
janzak-dev
marked this pull request as ready for review
September 29, 2026 10:45
VLukiantsev
reviewed
Sep 29, 2026
VLukiantsev
reviewed
Sep 29, 2026
VLukiantsev
reviewed
Sep 29, 2026
VLukiantsev
reviewed
Sep 29, 2026
Collaborator
Additional Out-of-Diff Alignment Observations (Group B)While reviewing the new rules in
|
VLukiantsev
approved these changes
Oct 5, 2026
Collaborator
There was a problem hiding this comment.
LGTM — all review feedback verified as addressed in 6514596. Thanks!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Section 9 ("Workflow Orchestration & Remote Automation Invariants") to
.agents/rules/skills_and_automation.md, updates.agents/rules/languages/shell.md, and refines.agents/skills/xmc_generate_release_notes/SKILL.mdto codify all actionable findings, review feedback, and orchestration invariants from PR #980.Motivation & Context
During the design and review cycles of PR #980 (
feat/add-xmc-release-skill), extensive review discussions identified recurring friction points in workflow orchestration: unpinned release tags (HEADvsorigin/main), fragile inline shell polling loops, lack of non-mutating preflight validation prior to confirmation gates, risks of autonomous--forcetag overwrites, lost multi-turn state across session restarts, scattered placeholder variables, and duplicate draft promotion logic.This PR codifies the complete set of invariants and best practices into shared repository rules and aligns
xmc_generate_release_notesto serve as the single source of truth for release publishing and promotion.Key Changes
.agents/rules/skills_and_automation.md):TARGET_SHA=$(git rev-parse origin/main)) for staging and release orchestration, verification, and validation automation scripts.headSha.startswith(target_sha)).tools/.--dry-run) (§9): Required non-mutating preflight validation before waiting on mandatory confirmation gates.--force(§9): Strictly prohibited autonomous--forceor tag overwrite actions.${ARTIFACT_DIR:-/tmp}/<file>.<ext>) and conditional fallback loading idiom (if [[ -z "${TARGET_SHA:-}" && -f "${STATE_FILE}" ]]; then TARGET_SHA=$(jq -r '.target_sha // empty' "${STATE_FILE}"); fi).VAR="<placeholder>").failed_jobs) over dumping raw build/test logs.|| trueerror suppression in Markdown skill snippets.#heading-slug) for cross-skill links..agents/rules/languages/shell.md):.agents/skills/xmc_generate_release_notes/SKILL.md):origin/main.BASE_TAG="<base_tag>",VERSION="<version>").publish_release.py ... --dry-run) in Section 5 prior to user review approval.--forceoverwrites.gh release edit "${TAG}" --draft=false).Assumptions
None — derived directly from PR #980 review discussions, reviewer consensus (VLukiantsev, AntonTyb), and retrospective findings.
Verification & Testing
./.githooks/pre-commit(All buildifier, gofmt, golangci-lint, go test determinism, addlicense, and ruff checks passed cleanly).bazel test //tools/...(All 80 Bazel unit tests passed cleanly across all tool packages)../tools/analyze_diff_size.py --base-ref origin/main...(0 prod lines, 0 test lines, 48 doc lines; 48 total code lines).🧪 Trajectory & Outcome Benchmark Results
📊 Trajectory & Outcome Comparison Report
scripts/release_candidate.shthat extracts release metadata for the next release usingtools/release/extract_release_metadata.pyand publishes a draft release usingtools/release/publish_release.py."Pillar 1: Trajectory Telemetry (Efficiency & Behavior)
🏆 Pre-Registered Scenario Verdict
Assertion Detail
file_exists scripts/release_candidate.shfile_contains scripts/release_candidate.shfile_exists scripts/release_candidate.shfile_contains scripts/release_candidate.shfile_exists scripts/verify_deployment.shfile_contains scripts/verify_deployment.shfile_exists scripts/local_lint_check.shfile_omits scripts/local_lint_check.shBenchmark Analysis & Verdict Rationale
HEADanti-pattern observed during release orchestration, pinningorigin/mainby default and adhering to${ARTIFACT_DIR:-/tmp}persistence. The baseline correctly failed to apply canonical remote pinning unprompted.verify_deployment.sh), widening Section 9 to explicitly cover verification/validation scripts and report persistence ensured the candidate pinned the target commit againstorigin/mainand persisted structured verification reports under${ARTIFACT_DIR:-/tmp}.local_lint_check.sh) correctly exempted local unstaged file checks from remoteorigin/mainfetching/pinning, demonstrating that the rule does not over-generalize to local developer scratch workflows.Related Issues / Bugs
N/A
TAG=agy
CONV=85ef69c5-6bd6-4ccb-bac3-6d26ad135417