diff --git a/.agents/skills/precheck-pr/SKILL.md b/.agents/skills/precheck-pr/SKILL.md index 9081ea0d..67c31895 100644 --- a/.agents/skills/precheck-pr/SKILL.md +++ b/.agents/skills/precheck-pr/SKILL.md @@ -15,6 +15,14 @@ This skill produces a local report. It does not itself authorize edits, commits, pushes, GitHub comments, or changing a PR's review status. Follow any separate user instructions for those actions. +## Confirm contributor intent + +First apply the canonical +[human contributor-intent gate](../self-review/SKILL.md#human-contributor-intent-gate). +It applies before implementation and submission, including draft PRs; reuse +explicit human answers, ask only what is missing, and wait. Independent read-only +review and automated review selection are outside this contributor gate. + ## Establish the review scope - Inspect the branch, remotes, working-tree status, and PR target when available. diff --git a/.agents/skills/self-review/SKILL.md b/.agents/skills/self-review/SKILL.md index b6dcf04a..15e4cb08 100644 --- a/.agents/skills/self-review/SKILL.md +++ b/.agents/skills/self-review/SKILL.md @@ -5,6 +5,8 @@ description: Self-review System1-Omni changes before requesting maintainer revie # System1-Omni self-review +Start with the [human contributor-intent gate](#human-contributor-intent-gate). + Follow the target checkout's `CONTRIBUTING.md` when present and its PR template. Review the full diff against the target branch for correctness, focused scope, architecture alignment and tests. Verify that documentation and PR claims match @@ -33,6 +35,48 @@ admission changes, check FIFO execution units, cancellation before dispatch, permit/resource retention after dispatch, and release on errors or panics against the [runtime contract](../../../src/runtime/README.md). +## Human contributor-intent gate + +Complete this gate with the human contributor before implementation and before +submitting a PR (including a draft). At pre-submit self-review, verify the answers +still describe the actual diff; ask again only where the scope or evidence changed. +This is a contributor preparation step, not a prerequisite for an independent +read-only review of someone else's PR, and it does not change automated review +selection or authorize any external action. + +Before submission, verify that the [PR template](../../../.github/PULL_REQUEST_TEMPLATE.md)'s +four required human answers and PR-necessity decision are complete and traceable, +and that bug-fix failure evidence is present when applicable. Blank fields, +placeholders, and agent-invented answers block implementation/submission. This is +a contributor workflow constraint; the Markdown template itself is not server-side +enforcement. Independent read-only reviews remain outside this gate. + +Use explicit human answers already present in the task, issue, or discussion, +keeping a traceable reference to their source. Ask only for missing or ambiguous +answers, then wait for the human; do not infer, invent, or answer on their behalf: + +1. What outcome are you trying to achieve? +2. What is the highest-leverage variable for that outcome? +3. How will this work move that variable rather than create busywork? +4. Who is the customer or user, and what do they actually need? + +After those answers are clear, ask the human: **Is a PR needed at all to achieve +this outcome?** Reuse an explicit, still-applicable human decision if already +recorded. If the answer is no or remains unclear, stop implementation/submission +and clarify the next step instead of manufacturing a change to justify a PR. + +For a bug fix, also link actual observed failure evidence, such as a minimal +reproduction with its observed result, a failing regression test, or a relevant +trace. Separate observed behavior from an untested diagnosis; a hypothetical +failure is not verified evidence. If the evidence is missing, ask for it or obtain +it within the authorized scope before proceeding. + +Keep source references in the working task and include only audience-appropriate, +authorized summaries or links in the PR. Do not copy private conversations, +customer data, or credentials into a public repository. Missing human answers +remain a blocker; an agent-written rationale or completed checklist cannot +substitute for them. + ## Conditional A/B checks Read [the benchmark self-review guidance](../../../benchmarks/README.md#self-review-and-ab-evidence) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 236829ca..8bc91e54 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,38 @@ +## Required human contributor answers + +Answer every question before implementation and PR submission, including drafts. +Reuse explicit, still-applicable human answers with a traceable source reference; +ask the human for anything missing and wait. An agent must not invent answers. +Blank fields, placeholders, or an agent-written rationale do not satisfy this gate. +Share only information and source links appropriate for this PR's audience. + +1. **What outcome are you trying to achieve?** + + Answer: + +2. **What is the highest-leverage variable for that outcome?** + + Answer: + +3. **How will this work move that variable rather than create busywork?** + + Answer: + +4. **Who is the customer or user, and what do they actually need?** + + Answer: + +**After answering the four questions: is a PR needed at all to achieve this outcome?** + +Human decision and rationale (or explicit source reference): + +**For a bug fix: link actual observed failure evidence.** +Include the observed result of a minimal reproduction, failing regression test, +or relevant trace. Label untested diagnoses as unverified. For a non-bugfix, +state why this is not applicable. + +Evidence: + ## Purpose diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea0321f5..b092bbaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,17 @@ Review the [README](README.md) and [architecture and integration contracts](docs/architecture.md) for the project's ownership boundaries and current implementation status before making changes. +## Before implementation or a PR + +Complete the [human contributor-intent gate](.agents/skills/self-review/SKILL.md#human-contributor-intent-gate) +before implementation and before submitting a PR, including a draft. It records +the human's outcome, highest-leverage variable, why the work moves it, customer +and actual need, then whether a PR is needed at all. Reuse explicit traceable +answers and ask only what is missing; wait rather than filling in answers for the +contributor. Bug fixes need linked observed failure evidence. Keep private source +material private. This contributor gate does not block independent read-only +reviews or change automated review selection. + ## Adding a model Keep model-specific preprocessing, execution and response formatting under