diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 79343ef7..4e8ad701 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 5a5de3fb..be60c3cd 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/AI_POLICY.md b/AI_POLICY.md index af63df12..56beb2e7 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 869ee11b..91fe525c 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 d047d182..682a40a6 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 62d281c1..89cdd5e3 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 e35c668e..3160c3a4 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 4eeb6231..ec2a0e22 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 00000000..cc4d01ba --- /dev/null +++ b/Docs/contributing/issue-policy.md @@ -0,0 +1,106 @@ +# 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. 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, + 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 64fd4905..e0e960cb 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,