chore: promote staging to staging-promote/9ba10eac-23686921981 (2026-03-28 15:07 UTC)

.github/pull_request_template.md

@@ -6,7 +6,7 @@
 
 ## Change Type
 
-<!-- Check one -->
+<!-- Check all that apply. Refactor-only PRs are for core team or maintainer-requested work. -->
 
 - [ ] Bug fix
 - [ ] New feature
@@ -18,16 +18,19 @@
 
 ## Linked Issue
 
-<!-- Closes #N, or "None" -->
+<!-- Closes #N, Fixes #N, Related #N, or "None". New feature PRs must link an approved issue. -->
 
 ## Validation
 
 <!-- How did you verify this works? -->
 
-- [ ] `cargo fmt`
-- [ ] `cargo clippy --all --benches --tests --examples --all-features`
+- [ ] `cargo fmt --all -- --check`
+- [ ] `cargo clippy --all --benches --tests --examples --all-features -- -D warnings`
+- [ ] `cargo build`
 - [ ] Relevant tests pass: <!-- list specific tests -->
+- [ ] `cargo test --features integration` if database-backed or integration behavior changed
 - [ ] Manual testing: <!-- describe what you tested -->
+- [ ] If a coding agent was used and supports it, `review-pr` or `pr-shepherd --fix` was run before requesting review
 
 ## Security Impact
 
@@ -45,6 +48,10 @@
 
 <!-- How to revert if this causes problems? For Track C changes, this is mandatory. -->
 
+## Review Follow-Through
+
+<!-- Review conversations are author-owned. Summarize any known follow-up or areas where reviewer judgment is still needed. -->
+
 ---
 
-**Review track**: <!-- A (docs/tests/chore) | B (feature/refactor) | C (security/runtime/DB/CI) -->
+**Review track**: <!-- A (docs/tests/chore) | B (feature/maintainer-requested refactor) | C (security/runtime/DB/CI) -->

.github/workflows/e2e.yml

@@ -1,6 +1,11 @@
 name: E2E Tests
 on:
   workflow_call:
+    inputs:
+      ref:
+        description: Commit SHA or ref to test
+        required: false
+        type: string
   schedule:
     - cron: "0 6 * * 1"  # Weekly Monday 6 AM UTC
   workflow_dispatch:
@@ -19,6 +24,8 @@ jobs:
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
 
       - uses: dtolnay/rust-toolchain@stable
 
@@ -59,6 +66,8 @@ jobs:
             files: "tests/e2e/scenarios/test_owner_scope.py tests/e2e/scenarios/test_routine_event_batch.py"
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
 
       - name: Download binary
         uses: actions/download-artifact@v4

.github/workflows/staging-ci.yml

@@ -62,7 +62,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: staging
+          ref: ${{ github.sha }}
           fetch-depth: 0
           fetch-tags: true
 
@@ -117,13 +117,17 @@ jobs:
     needs: check-changes
     if: needs.check-changes.outputs.has_changes == 'true'
     uses: ./.github/workflows/test.yml
+    with:
+      ref: ${{ needs.check-changes.outputs.current_head }}
 
   # ── Run E2E browser tests ────────────────────────────────────────
   e2e:
     name: E2E Browser Tests
     needs: check-changes
     if: needs.check-changes.outputs.has_changes == 'true'
     uses: ./.github/workflows/e2e.yml
+    with:
+      ref: ${{ needs.check-changes.outputs.current_head }}
 
   # ── Create promotion PR (triggers claude-review.yml on the PR) ──
   create-promotion-pr:
@@ -137,7 +141,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: staging
+          ref: ${{ needs.check-changes.outputs.current_head }}
           fetch-depth: 0
 
       - name: Generate GitHub App token
@@ -163,7 +167,7 @@ jobs:
           PROMOTION_BASE: ${{ needs.resolve-promotion-base.outputs.promotion_base }}
         run: |
           git fetch origin "${PROMOTION_BASE}"
-          AHEAD=$(git rev-list --count "origin/${PROMOTION_BASE}..origin/staging")
+          AHEAD=$(git rev-list --count "origin/${PROMOTION_BASE}..HEAD")
           echo "commits_ahead=${AHEAD}" >> "$GITHUB_OUTPUT"
           if [ "$AHEAD" -eq 0 ]; then
             echo "Staging is not ahead of ${PROMOTION_BASE}. Nothing to promote."

.github/workflows/test.yml

@@ -1,6 +1,11 @@
 name: Run Tests
 on:
   workflow_call:
+    inputs:
+      ref:
+        description: Commit SHA or ref to test
+        required: false
+        type: string
   pull_request:
     branches:
       - main
@@ -29,6 +34,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -52,6 +59,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -80,6 +89,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
@@ -107,6 +118,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
@@ -125,6 +138,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
         with:
@@ -147,6 +162,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
@@ -164,6 +181,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
       - name: Build Docker image
         run: docker build -t ironclaw-test:ci .
 
@@ -175,6 +194,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
+          ref: ${{ inputs.ref || github.sha }}
           fetch-depth: 0
       - name: Check version bumps for changed extensions
         env:

CONTRIBUTING.md

@@ -10,6 +10,42 @@ cd ironclaw
 
 This installs the Rust toolchain, WASM targets, git hooks, and runs initial checks.
 
+## How to Contribute
+
+- Bug fixes, docs improvements, and focused cleanup tied to a concrete problem are welcome.
+- Search existing issues and PRs before opening a new one to avoid duplicates.
+- Keep changes scoped. One bug, one feature, or one documentation improvement per PR.
+
+### Creating Issues
+
+Open an issue when you are reporting a bug, proposing a feature, or documenting a gap in behavior.
+
+For bug reports, include:
+
+- What you expected to happen
+- What actually happened
+- Clear reproduction steps
+- Relevant logs, screenshots, or error output
+- Environment details when they matter (OS, database backend, feature flags, commit/branch)
+
+For feature requests:
+
+- Open an issue first before writing code
+- Explain the problem being solved, not just the implementation idea
+- Wait for maintainer feedback before investing in a large PR
+
+We require an issue for new features so maintainers can prioritize the work and confirm it fits the roadmap before anyone spends time implementing it.
+
+### Fixing Bugs
+
+- Small, targeted bug-fix PRs are welcome
+- If there is already an issue, link it in your PR
+- If the bug is non-trivial, security-sensitive, or changes behavior across subsystems, open or confirm an issue first so the approach can be aligned before implementation
+
+### Refactor-Only PRs
+
+Refactor-only PRs are not accepted from contributors outside the core team. If a refactor is necessary to land a bug fix or approved feature, keep it minimal and clearly tied to that change.
+
 ## Development Workflow
 
 ```bash
@@ -19,6 +55,45 @@ cargo test                                                   # unit tests
 cargo test --features integration                            # + PostgreSQL tests
 ```
 
+These commands are for day-to-day iteration while you are developing locally. The pre-submission checks below are intentionally stricter and use CI-style flags so you can catch formatting drift and clippy warnings before requesting review.
+
+## Before You Open a PR
+
+Run the local validation checks required before requesting a review. These are stricter than the commands for iterative development:
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --all --benches --tests --examples --all-features -- -D warnings
+cargo build
+cargo test
+```
+
+Also run this when your change touches database-backed or integration behavior:
+
+```bash
+cargo test --features integration
+```
+
+Before asking for review:
+
+- Build and exercise the changed path locally, not just the narrowest unit test
+- Keep the PR focused and avoid mixing unrelated concerns
+- Fill out the PR template with a clear summary, validation notes, and impact assessment
+- If your change affects tracked behavior, update `FEATURE_PARITY.md` in the same branch
+- If onboarding or setup behavior changes, update the relevant setup docs in the same branch
+- If you are using a coding agent and it supports them, run `review-pr` or `pr-shepherd --fix` before opening or updating the PR
+- `codex review --base origin/main` is also encouraged before requesting review
+
+## Review Follow-Through
+
+Review conversations are author-owned.
+
+- Address each review comment with a code change or a clear explanation
+- Resolve conversations you have handled; leave them open only when reviewer judgment is still needed
+- Do not leave review cleanup for maintainers when the follow-through belongs to the author
+
+If a PR is stale for more than 48 hours after review feedback is posted, maintainers may take over the follow-up work and land the changes needed to accomplish the original PR or issue intent.
+
 ## Code Style
 
 - Zero clippy warnings policy
@@ -46,7 +121,7 @@ All PRs follow a risk-based review process:
 | Track | Scope | Requirements |
 |-------|-------|-------------|
 | **A** | Docs, tests, chore, dependency bumps | 1 approval + CI green |
-| **B** | Features, refactors, new tools/channels | 1 approval + CI green + test evidence |
+| **B** | Features, maintainer-requested refactors, new tools/channels | 1 approval + CI green + test evidence |
 | **C** | Security (`src/safety/`, `src/secrets/`), runtime (`src/agent/`, `src/worker/`), database schema, CI workflows | 2 approvals + rollback plan documented |
 
 Select the appropriate track in the PR template based on what your changes touch.