From 1a657e7ffb753ed67981e39c0e0c76627528f148 Mon Sep 17 00:00:00 2001 From: Brad Byrd Date: Thu, 8 Oct 2026 08:49:46 -0500 Subject: [PATCH 1/2] docs: define agent issue handling policy --- AI_POLICY.md | 10 ++- CLAUDE.md | 6 +- CONTRIBUTING.md | 1 + Docs/README.md | 1 + Docs/contributing/contributing-guide.md | 1 + Docs/contributing/index.md | 9 ++- Docs/contributing/issue-policy.md | 103 ++++++++++++++++++++++++ GOVERNANCE.md | 23 ++++-- 8 files changed, 142 insertions(+), 12 deletions(-) create mode 100644 Docs/contributing/issue-policy.md diff --git a/AI_POLICY.md b/AI_POLICY.md index af63df120..56beb2e74 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -60,6 +60,10 @@ If an AI-generated contribution introduces bugs, license problems, or policy violations, the **human author** (and any reviewing Maintainer who merges it) bears responsibility the same as for hand-written work. +For project-run agents acting under the standing I1 delegation in +[the issue policy](Docs/contributing/issue-policy.md), Maintainers remain +accountable for that automation and may revoke the delegation. + --- ## 4. What is forbidden (discrimination) @@ -112,7 +116,11 @@ security research assistance, and automation, subject to: - No pasting private vulnerability details into untrusted third-party tools when that would violate [SECURITY.md](SECURITY.md) handling - No committing secrets -- Human sign-off on merges and releases +- Human sign-off on releases and on merges outside the I1 delegation in + [the issue policy](Docs/contributing/issue-policy.md) + +Project-run agents follow the ranked dispatch rules in +[Docs/contributing/issue-policy.md](Docs/contributing/issue-policy.md). --- diff --git a/CLAUDE.md b/CLAUDE.md index 869ee11b1..91fe525c0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,9 +11,10 @@ Binding community and contribution policy lives at the **repo root** (not only u |---|---| | `GOVERNANCE.md` | Authority, roles (Maintainer / Contributor / Participant), decision rights, binding technical policies | | `CODE_OF_CONDUCT.md` | Community standards and enforcement | -| `AI_POLICY.md` | **AI-assisted work is welcome** — WFL was built with AI; do not discriminate against AI use; human author remains accountable | +| `AI_POLICY.md` | **AI-assisted work is welcome** — WFL was built with AI; do not discriminate against AI use; human authors and project-run automation remain accountable | | `CONTRIBUTING.md` | How to contribute; **Contributor application** process (Discussion or email) | | `SECURITY.md` | Private vulnerability reporting only — never file security bugs as public issues | +| `Docs/contributing/issue-policy.md` | Ranked issue types and agent dispatch, merge, and closure rules | | `testing.md` | **Binding Logbie Testing Policy + WFL testing profile** — Red→Green TDD evidence, required test layers, risk classes, and merge/release gates (see **Testing Policy** below) | | `REPOSITORY_HYGIENE.md` | **Binding Repository Hygiene and Layout Policy** — canonical home for every class of content, tracked-vs-ephemeral rules, approved output roots, archive manifest, exceptions; profile in `.repo-hygiene.toml`, enforced by `scripts/check_repo_hygiene.py` in CI | @@ -25,7 +26,8 @@ Binding community and contribution policy lives at the **repo root** (not only u - **Docs ship with the feature** — same change; validate examples; Dev Diary entry under `History/dev-diary//` for non-trivial work. - **Hygiene is enforced** — every file has one canonical home (`REPOSITORY_HYGIENE.md`); tests and tools write only under `target/` or temp dirs; never track dumps, logs, caches, local settings, or personal paths. The `repo-hygiene` CI job blocks violations — fix placement, don't widen allowlists. - **Quality gates** — `cargo fmt`, `clippy -D warnings`, `cargo test`; conventional commits. -- **Do not invent maintainer identity or process** — Contributor status is by application; Maintainers own merges and releases unless those responsibilities are **explicitly delegated**. Prefer first name **Brad** only if referring to the primary maintainer in docs (no last name). +- **Do not invent maintainer identity or process** — Contributor status is by application; Maintainers own releases and non-delegated merges. The narrow I1 agent merge delegation is in `Docs/contributing/issue-policy.md`. Prefer first name **Brad** only if referring to the primary maintainer in docs (no last name). +- **Classify issues before agent dispatch** — project-run agents may fix, merge, and close well-defined I1 bugs after required CI, review-bot, and testing gates pass. New features and unclear behavior need a Maintainer's dispatch decision. Follow `Docs/contributing/issue-policy.md` and escalate sensitive work. - Community tone: follow `CODE_OF_CONDUCT.md`; technical disagreement is fine; harassment and AI-shaming are not. When changing contribution workflow, community rules, or project authority, update the root governance suite **and** keep this section accurate. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d047d1823..682a40a69 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,7 @@ governance suite below. | [GOVERNANCE.md](GOVERNANCE.md) | Who decides what; binding technical policies | | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards | | [AI_POLICY.md](AI_POLICY.md) | AI-assisted work is welcome | +| [Docs/contributing/issue-policy.md](Docs/contributing/issue-policy.md) | Which issue types agents may fix, merge, and close autonomously | | [SECURITY.md](SECURITY.md) | Private vulnerability reporting | | [REPOSITORY_HYGIENE.md](REPOSITORY_HYGIENE.md) | Where content belongs; what may be tracked; approved output roots | | [Docs/contributing/contributing-guide.md](Docs/contributing/contributing-guide.md) | Fork, TDD, fmt/clippy/test, docs validation | diff --git a/Docs/README.md b/Docs/README.md index 62d281c11..89cdd5e3b 100644 --- a/Docs/README.md +++ b/Docs/README.md @@ -232,6 +232,7 @@ Guidelines for quality, security, performance, and collaboration — aligned wit - **[Contributing index](contributing/index.md)** - Overview of contributor docs (active designs live in `Engineering/`, history in `History/`, retired material in `Archive/` — see [REPOSITORY_HYGIENE.md](../REPOSITORY_HYGIENE.md)) - **[Building from Source](contributing/building-from-source.md)** - Compile WFL - **[Contributing Guide](contributing/contributing-guide.md)** - Day-to-day contribution workflow +- **[Issue Policy](contributing/issue-policy.md)** - Ranked issue types and agent dispatch, merge, and closure rules - **[Architecture Overview](contributing/architecture-overview.md)** - How WFL works - **[LSP Integration](contributing/lsp-integration.md)** - Language Server details - **[MCP Integration](contributing/mcp-integration.md)** - AI assistant integration diff --git a/Docs/contributing/contributing-guide.md b/Docs/contributing/contributing-guide.md index e35c668eb..3160c3a40 100644 --- a/Docs/contributing/contributing-guide.md +++ b/Docs/contributing/contributing-guide.md @@ -11,6 +11,7 @@ code, documentation, tests, and examples. | [GOVERNANCE.md](../../GOVERNANCE.md) | Who decides; binding technical policies | | [CODE_OF_CONDUCT.md](../../CODE_OF_CONDUCT.md) | Community standards | | [AI_POLICY.md](../../AI_POLICY.md) | AI-assisted contributions are welcome | +| [Issue policy](issue-policy.md) | Agent dispatch, merge, and closure rules by issue type | | [SECURITY.md](../../SECURITY.md) | Private security reporting | ## Getting Started diff --git a/Docs/contributing/index.md b/Docs/contributing/index.md index 4eeb6231b..ec2a0e22b 100644 --- a/Docs/contributing/index.md +++ b/Docs/contributing/index.md @@ -11,10 +11,11 @@ Development work still follows the [WFL foundation](../wfl-foundation.md): clear 1. **[Building from Source](building-from-source.md)** — Install Rust, clone, build, test, run 2. **[Contributing Guide](contributing-guide.md)** — How to propose and land changes -3. **[Architecture Overview](architecture-overview.md)** — Compiler pipeline and major components -4. **[LSP Integration](lsp-integration.md)** — Language Server for editors -5. **[MCP Integration](mcp-integration.md)** — AI assistant tools (parse, analyze, typecheck, lint) -6. **[Compiler Internals](compiler-internals.md)** — Deeper implementation notes +3. **[Issue Policy](issue-policy.md)** — Ranked issue types and agent dispatch, merge, and closure rules +4. **[Architecture Overview](architecture-overview.md)** — Compiler pipeline and major components +5. **[LSP Integration](lsp-integration.md)** — Language Server for editors +6. **[MCP Integration](mcp-integration.md)** — AI assistant tools (parse, analyze, typecheck, lint) +7. **[Compiler Internals](compiler-internals.md)** — Deeper implementation notes ## Design notes diff --git a/Docs/contributing/issue-policy.md b/Docs/contributing/issue-policy.md new file mode 100644 index 000000000..45baa1af9 --- /dev/null +++ b/Docs/contributing/issue-policy.md @@ -0,0 +1,103 @@ +# Issue policy: agent dispatch and resolution + +This policy ranks issues by the authority given to an AI agent **before a fix +starts and before it merges**. It applies to project-run agents and to anyone +dispatching work to them. +It does not restrict a person from using AI while preparing a contribution: +[AI_POLICY.md](../../AI_POLICY.md) applies equally to all contributors. + +**Dispatch** means assigning or starting implementation, including a fix PR. +Agents may investigate, reproduce, and propose a scope before dispatch unless +the issue requires private handling. **Autonomous** I1 work needs no human +approval before dispatch. It may merge and close without human approval when +the review bots and branch rules satisfy every I1 completion gate below. +This is a narrow, standing delegation from the Maintainers under +[GOVERNANCE.md](../../GOVERNANCE.md); it grants no release or general triage +authority. Closing an issue without a merged fix (for example, as duplicate or +not planned) still requires a Maintainer or delegated Contributor decision. + +## Ranked issue types + +Apply the highest applicable type. These issue types govern **dispatch**; +`R0`–`R3` in [testing.md](../../testing.md#5-change-risk-classes) separately +govern test and review evidence. A low testing risk class does not override a +human decision required below. + +| Rank | Issue type | Typical issues | Agent authority before a fix | +|---|---|---|---| +| **I1** | Well-defined bug or routine correction, autonomous | A reproducible internal or user-visible bug whose expected behavior is already established; a prose typo or broken link with an unambiguous correction; a test or fixture correction that preserves intended behavior without weakening a required gate | May investigate, self-dispatch, open a PR, then merge and close the linked issue after the I1 completion gates pass. | +| **I2** | Human review before dispatch | Any new feature or enhancement; a bug that needs a product or design decision; speculative performance work; dependency, CI, packaging, installer, or configuration changes; unclear acceptance criteria or disputed expected behavior | May triage and propose a fix. A Maintainer must confirm the scope and authorize dispatch in the issue or linked discussion before implementation starts. | +| **I3** | Maintainer-led, restricted | Potential vulnerabilities or secrets; changes to security boundaries or protected data; new or breaking language syntax or semantics; compatibility exceptions, destructive migrations, release controls, registry trust, governance, legal/licensing, Code of Conduct, or access and permission decisions | Do not self-dispatch. A Maintainer chooses the handling channel, decision, scope, and whether to assign any implementation to an agent. Security reports follow [SECURITY.md](../../SECURITY.md) privately. | + +I1 applies to bugs when the agent can reproduce the failure, explain the +observed and expected behavior using an existing contract, and state a bounded +acceptance test. A new behavior choice, even when proposed as a bug fix, is I2. +An `R2` or `R3` testing risk class does not by itself prevent autonomous +dispatch of a well-defined bug; the agent must still meet every test and review +gate for that risk class before merge. An I3 security or authority decision +always takes precedence. Executable changes default to `R2` under `testing.md`; +an agent claiming `R1` must explain why no public contract, persistent state, +security boundary, process boundary, or critical journey can be affected. The +required reviewer confirms that claim before merge. An `R0` classification +likewise requires proof that shipped behavior is unchanged. + +## I1 completion gates + +An agent may merge an I1 PR and close its linked issue when **all** of these +conditions hold. Human sign-off is unnecessary when qualifying bot review +satisfies the required approvals: + +1. The issue still qualifies as I1 after implementation. The PR links the + issue and records the expected behavior, risk class, acceptance criteria, + tests, and evidence required by `testing.md`. +2. All required CI checks pass on the final PR head and the latest target branch + or merge-queue result. Pending, skipped, waived, flaky, and known-failing + required checks are not passes. Relevant test layers outside CI must also + pass when `testing.md` requires them. +3. At least one review bot independent of the author agent has examined the + final diff and evidence, along with any other required review bots. The + agent addresses each actionable finding with a fix or a documented, + technically supported response, and no blocking finding or required bot + approval remains outstanding. A bot that merely repeats the author's claims + does not satisfy an independent-review requirement. For `R3`, the required + qualified independent review, including security-focused review when + applicable, must be complete. If no suitable bot review is available, a + human reviewer must provide the missing review before merge. +4. Branch protection and required review rules permit the merge without a + bypass. The agent does not grant itself access, dismiss a required review, + or weaken CI to make the PR eligible. A comment-only bot review does not + satisfy a required approving review; if a qualifying bot approval is + unavailable, obtain the required human approval before merge. + +After the merge succeeds, the agent may close the linked issue with the merged +PR and verification evidence. A merge keyword that closes the issue on merge +also satisfies this step. If any gate fails or the change expands beyond I1, +pause and seek a Maintainer decision. + +## Triage and escalation + +1. Check for a possible vulnerability or exposed secret first. Do not copy its + details into a public issue or an untrusted tool; use the private process in + `SECURITY.md`. Treat it as I3 even if the proposed patch looks small. +2. Record the issue type, short rationale, expected outcome, and testing risk + class in the issue or linked PR. For I2, link the Maintainer's dispatch + decision. For I3, use the channel selected by the Maintainer. +3. If the issue fits more than one type, choose the higher rank. If facts are + missing, default to I2; if a sensitive or I3 trigger is plausible, use I3. + An agent may continue read-only investigation but must pause implementation + until the required decision is recorded. +4. Reclassify upward and stop the fix if investigation reveals broader behavior, + compatibility, security, or authority impact. Obtain the new dispatch + decision before resuming. Do not split an issue merely to evade a gate. +5. For every dispatched fix, follow [testing.md](../../testing.md), the + documentation and compatibility rules in `GOVERNANCE.md`, and the PR process. + CI passing is necessary for I1 merge and closure, together with the review + and evidence gates above. Releases remain Maintainer decisions. + +**Examples:** A broken prose link is I1 if its target is obvious. A compiler +diagnostic that contradicts an existing documented rule is I1 when it has a +reproduction and a clear expected message. A request for a new diagnostic is +I2. A parser bug with a documented expected result can be I1 even when its +testing risk is `R3`; an independent review and all `R3` evidence still apply. +A public issue that appears to expose a credential is I3 and moves to private +handling. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 64fd49059..e0e960cbf 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -9,6 +9,7 @@ repository so contributors have a single source of truth. |---|---| | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community behavior and enforcement | | [AI_POLICY.md](AI_POLICY.md) | AI-assisted work is welcome; anti-discrimination | +| [Docs/contributing/issue-policy.md](Docs/contributing/issue-policy.md) | Ranked issue types and agent dispatch, merge, and closure rules | | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute and apply for Contributor status | | [SECURITY.md](SECURITY.md) | Vulnerability reporting and supported versions | | [REPOSITORY_HYGIENE.md](REPOSITORY_HYGIENE.md) | Binding repository hygiene and layout policy (§3.8) | @@ -46,7 +47,7 @@ and, over time, **Maintainers**. | Role | Who | Rights and duties | |---|---|---| -| **Maintainer** | Brad (Logbie LLC); additional people may be appointed | Final authority on technical direction, merges to protected branches, releases, security response, governance changes, trademark/project identity, and Contributor appointments | +| **Maintainer** | Brad (Logbie LLC); additional people may be appointed | Final authority on technical direction, merge policy and non-delegated merges to protected branches, releases, security response, governance changes, trademark/project identity, and Contributor appointments | | **Contributor** | People granted write access after application and approval | Open PRs from branches, review others’ work, triage issues as delegated, help enforce the Code of Conduct as delegated. Does **not** alone merge to `main` unless also a Maintainer or explicitly delegated for a path | | **Participant** | Anyone who opens issues, discussions, or PRs from a fork | Propose changes, report bugs, improve docs; must follow the Code of Conduct | @@ -58,7 +59,7 @@ may care about. | Decision type | Who decides | Notes | |---|---|---| -| Day-to-day PR merge | Maintainer(s) | Based on review, CI, and project policies below | +| Day-to-day PR merge | Maintainer(s); project-run agents for eligible I1 fixes under §3.9 | Based on review, CI, and project policies below | | Language design / breaking change | Maintainer(s) | Must satisfy backward-compatibility rules | | Security advisories and embargo | Maintainer(s) | Per [SECURITY.md](SECURITY.md) | | Appointing Contributors / Maintainers | Maintainer(s) | See [CONTRIBUTING.md](CONTRIBUTING.md) application process | @@ -178,6 +179,16 @@ process. The machine-readable profile is `.repo-hygiene.toml`; Widening an allowlist to silence a violation without Maintainer approval is itself a policy violation. +### 3.9 Agent issue handling + +[The issue policy](Docs/contributing/issue-policy.md) delegates dispatch, +merge, and linked-issue closure for well-defined I1 bug fixes and routine +corrections to project-run AI agents after required CI and review-bot gates +pass. New features and unclear behavior need a Maintainer's dispatch decision +and human merge approval. This delegation does not extend to releases, +security response, or general issue triage. Human contributors may use AI under +`AI_POLICY.md` regardless of issue type. + --- ## 4. Contribution paths @@ -207,9 +218,11 @@ is no automatic promotion timeline; appointments are explicit and public 3. Update docs, tests, and Dev Diary as required by §3. 4. Open a PR with a clear summary, motivation, test notes, and compatibility impact (template in the collaboration guide). -5. Address review feedback. AI-assisted work is welcome; the human author is - accountable (see [AI_POLICY.md](AI_POLICY.md)). -6. Maintainer merges when checks and policies are satisfied. +5. Address review feedback. AI-assisted work is welcome; accountability + follows [AI_POLICY.md](AI_POLICY.md). +6. A Maintainer merges when checks and policies are satisfied, except that a + project-run agent may merge an eligible I1 fix under §3.9 after its required + CI, review, and evidence gates pass. Maintainers may reject or request changes for any reason grounded in these policies, including style that violates WFL’s natural-language design goals, From dffa69d3f23268254c055b48de078b8a5453ad9c Mon Sep 17 00:00:00 2001 From: Brad Byrd Date: Thu, 8 Oct 2026 08:56:44 -0500 Subject: [PATCH 2/2] ci: run required checks for dev pull requests --- .github/workflows/ci.yml | 2 +- .github/workflows/wfl-config-lint.yml | 2 +- Docs/contributing/issue-policy.md | 7 +++++-- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 79343ef71..4e8ad701d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,7 @@ on: push: branches: [ main ] pull_request: - branches: [ main ] + branches: [ main, dev ] # Without this, every push to a branch leaves the previous run compiling a # commit whose result nobody will ever read. A superseded clippy-and-test run diff --git a/.github/workflows/wfl-config-lint.yml b/.github/workflows/wfl-config-lint.yml index 5a5de3fb5..be60c3cd2 100644 --- a/.github/workflows/wfl-config-lint.yml +++ b/.github/workflows/wfl-config-lint.yml @@ -4,7 +4,7 @@ on: push: branches: [ main ] pull_request: - branches: [ main ] + branches: [ main, dev ] permissions: contents: read diff --git a/Docs/contributing/issue-policy.md b/Docs/contributing/issue-policy.md index 45baa1af9..cc4d01ba2 100644 --- a/Docs/contributing/issue-policy.md +++ b/Docs/contributing/issue-policy.md @@ -52,8 +52,11 @@ satisfies the required approvals: tests, and evidence required by `testing.md`. 2. All required CI checks pass on the final PR head and the latest target branch or merge-queue result. Pending, skipped, waived, flaky, and known-failing - required checks are not passes. Relevant test layers outside CI must also - pass when `testing.md` requires them. + required checks are not passes. The PR's target branch must trigger the + workflows that produce those checks; a branch rule that requires a check + does not run it. If a required check has no run for this PR, autonomous + merge is blocked. Relevant test layers outside CI must also pass when + `testing.md` requires them. 3. At least one review bot independent of the author agent has examined the final diff and evidence, along with any other required review bots. The agent addresses each actionable finding with a fix or a documented,