diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..4e7263c9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +# Summary + +Describe the final change and owning issue. + +## Compatibility and risk + +Risk class, affected contracts, exceptions and unresolved controls. + +## Validation + +Current SHA, exact commands/results, Actions links, Red/Green or justified +documentation-only N/A. Record missing/skipped checks as Not run with reason. + +## Checklist + +- [ ] Feature/fix/docs branch targets `dev`; no direct protected-branch push. +- [ ] Current SHA, Actions run links and individual required results are recorded. +- [ ] Red/Green evidence, or justified documentation-only N/A with doc/link checks. +- [ ] Skipped, missing, pending and failed checks are explicit, never called passes. +- [ ] Yomi reviewed this revision; material fixes have fresh CI and review. +- [ ] Triggered bot reviews finished; findings/discussions are fixed or dispositioned. +- [ ] PR owner has a real monitor/event continuation while checks or reviews are pending. +- [ ] No secrets/private data; environment injection and production boundaries observed. +- [ ] No protection bypass; check/review state is rechecked immediately before merge. +- [ ] Main/release/tag/deploy authority and Brad-reserved decisions follow GOVERNANCE.md. diff --git a/.github/workflows/docker-image.yml b/.github/workflows/docker-image.yml index 9d463765..5a896fc8 100644 --- a/.github/workflows/docker-image.yml +++ b/.github/workflows/docker-image.yml @@ -2,7 +2,7 @@ name: Docker Runtime Validation on: pull_request: - branches: [main] + branches: [main, dev] paths: - '.github/workflows/docker-image.yml' - '.github/workflows/nightly.yml' diff --git a/AI_POLICY.md b/AI_POLICY.md index 56beb2e7..d3c44ec9 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -1,5 +1,9 @@ # AI Policy — Inclusion, Not Discrimination +Contribution authority, feature → `dev` PRs, exact-commit CI, Yomi review, +bot feedback, secrets and production boundaries follow +[GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27). + ## Summary **WFL was built with AI assistance. AI-assisted contributions are welcome.** @@ -118,6 +122,8 @@ security research assistance, and automation, subject to: - No committing secrets - Human sign-off on releases and on merges outside the I1 delegation in [the issue policy](Docs/contributing/issue-policy.md) +- Yomi review of the current revision, following + [GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27) 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 91fe525c..4fa86749 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,9 @@ # CLAUDE.md +Contribution authority, feature → `dev` PRs, exact-commit CI, Yomi review, +bot feedback, secrets and production boundaries follow +[GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27). + This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Governance (do not dig — start here) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 682a40a6..b069cdf4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,9 @@ # Contributing to WFL +Contribution authority, feature → `dev` PRs, exact-commit CI, Yomi review, +bot feedback, secrets and production boundaries follow +[GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27). + Thank you for your interest in WebFirst Language (WFL). This document is the root entry point for contribution policy. Day-to-day workflow detail lives in the development guide; **project authority and community rules** live in the @@ -14,7 +18,8 @@ governance suite below. | [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 | -| [Docs/06-best-practices/collaboration-guide.md](Docs/06-best-practices/collaboration-guide.md) | PR template, reviews, commits | +| [`.github/pull_request_template.md`](.github/pull_request_template.md) | Canonical pull request template | +| [Docs/06-best-practices/collaboration-guide.md](Docs/06-best-practices/collaboration-guide.md) | Reviews, commits, collaboration practices | | [Docs/wfl-foundation.md](Docs/wfl-foundation.md) | Design principles | By participating, you agree to the Code of Conduct and AI Policy. @@ -34,10 +39,10 @@ You do **not** need to be a formal Contributor to help. From a fork you can: ### Quick start 1. Fork https://github.com/WebFirstLanguage/wfl -2. Create a branch: `git checkout -b feature/my-change` +2. Create a branch from current dev: `git checkout -b feature/my-change origin/dev` 3. Follow TDD and quality gates in the [contributing guide](Docs/contributing/contributing-guide.md) -4. Open a pull request with a clear description +4. Open a pull request into `dev` with a clear description ### Non-negotiable project rules (summary) diff --git a/Docs/06-best-practices/collaboration-guide.md b/Docs/06-best-practices/collaboration-guide.md index bca904c2..626ae09a 100644 --- a/Docs/06-best-practices/collaboration-guide.md +++ b/Docs/06-best-practices/collaboration-guide.md @@ -51,36 +51,18 @@ Working with others on WFL projects requires clear communication and consistent ## Pull Requests -### PR Description Template +### PR description template -```markdown -## Summary -Brief description of changes - -## Motivation -Why this change is needed - -## Changes -- Added feature X -- Fixed bug Y -- Updated documentation Z +Use the single canonical template at +[`.github/pull_request_template.md`](../../.github/pull_request_template.md). +GitHub applies it to new pull requests. Do not copy an older local template. -## Testing -- Created test_feature.wfl -- All tests pass -- Tested manually with... +### Repository contribution authority -## Backward Compatibility -- [x] No breaking changes -- [ ] Breaking change (explain below) - -## Checklist -- [x] Tests added -- [x] Documentation updated -- [x] cargo fmt run -- [x] cargo clippy clean -- [x] All TestPrograms pass -``` +Follow [GOVERNANCE.md](../../GOVERNANCE.md) for feature → `dev` PRs, +Yomi review, exact-commit Actions evidence, bot feedback and promotion +authority. Maintainers merge; the only standing exception is an eligible I1 +fix by a project-run agent under GOVERNANCE.md §3.9. ### Before Submitting PR diff --git a/Docs/contributing/contributing-guide.md b/Docs/contributing/contributing-guide.md index 3160c3a4..344b7360 100644 --- a/Docs/contributing/contributing-guide.md +++ b/Docs/contributing/contributing-guide.md @@ -18,10 +18,11 @@ code, documentation, tests, and examples. 1. **Fork** the repository 2. **Clone** your fork -3. **Create branch:** `git checkout -b feature/my-feature` +3. **Create branch:** `git checkout -b feature/my-feature origin/dev` 4. **Make changes** (TDD — tests first) 5. **Test thoroughly** -6. **Submit PR** +6. **Submit PR into `dev`**; follow the current-revision CI, Yomi review and + authority gates in [GOVERNANCE.md](../../GOVERNANCE.md). Want trusted collaborator access? See [Becoming a Contributor](../../CONTRIBUTING.md#becoming-a-contributor). @@ -78,6 +79,9 @@ python scripts/validate_docs_examples.py --file path/to/example.wfl ### 4. Create PR +Use the canonical template at +[`.github/pull_request_template.md`](../../.github/pull_request_template.md). + **PR should include:** - Clear description of changes - Tests for new features/fixes diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e0e960cb..257c0971 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -15,10 +15,103 @@ repository so contributors have a single source of truth. | [REPOSITORY_HYGIENE.md](REPOSITORY_HYGIENE.md) | Binding repository hygiene and layout policy (§3.8) | | [Docs/contributing/contributing-guide.md](Docs/contributing/contributing-guide.md) | Day-to-day development workflow | | [Docs/wfl-foundation.md](Docs/wfl-foundation.md) | 19 guiding principles and the No-Unlearning Invariant | +| [testing.md](testing.md) | Binding testing policy and WFL profile | | [LICENSE](LICENSE) | Apache License 2.0 | --- +## Common contribution policy — version 1.0 (2026-09-27) + +This version records Brad's approved Logbie LLC governance and subsequent CEO +delegations of 2026-09-26, reconciled with the Maintainer merge rule and I1 +exception. It governs contribution authority; the repository's technical, +compatibility, testing and licensing rules remain binding. Report substantive +conflicts on the owning issue instead of silently relaxing a rule. + +### Branches and review + +- Start a short-lived feature, fix or documentation branch from current `dev`; + open its PR into `dev`. Never push directly to `dev`, `main` or a release + branch, or force-push shared branches. Promotion is `dev → main` by PR. +- Yomi reviews the current revision against governance and testing policy. +- Maintainers merge. The only standing exception is an eligible I1 fix by a + project-run agent under §3.9 and + [the issue policy](Docs/contributing/issue-policy.md). Authors, including + agent authors, do not merge their own pull requests. This needs no separate + per-PR Brad approval once the ruleset, reviews, and CI below are satisfied. +- GitHub ruleset **LOG-16 reviewed changes** is enforced on `main` and `dev` + with no bypass. It requires one approving review from someone other than the + author (approvals are dismissed on a new push), all review threads resolved, + the branch up to date with its base, merge commits only, and the 12 required + status checks passing. The ruleset blocks a merge that lacks that independent + approval. +- Let triggered bot reviews finish; inspect reviews, inline comments and + discussions. Fix actionable findings or record a reasoned disposition and + resolve required discussions. Recheck checks and reviews immediately before + merging. Material changes require fresh applicable CI and Yomi review. +- The PR owner remains responsible while CI or bot review is pending. Use an + actual scheduled monitor or event-driven continuation, not a promise to watch. +- Do not bypass protections, use an administrator override, remove a check, or + rerun a genuine failure merely to manufacture green. Access is not authority. + +### Evidence and testing + +- Behavior changes start with a test failing for the intended reason, followed + by implementation and passing evidence. Retain exact commands, revisions, + results and run links under the repository testing policy. +- GitHub Actions on the current reviewed revision is merge evidence; local + checks supplement it. Enumerate required jobs and their individual results. + Missing tools, environment failures, missing/pending checks and skipped, + cancelled or failed required suites are blocked verification, never passes. + An aggregate green result cannot stand in for an unrun required suite. +- For prose-only work, record “Behavior tests N/A — documentation only” with + the reason and relevant documentation, link and policy checks. This does not + waive required CI. Existing risk classes and stricter technical gates remain. +- Run agent-operated runtime tests on Starnet test VM 136 or 104, never VM 143; + coordinate risky-test snapshots with Nodoka. Preserve the repository's approved + GitHub Actions execution environments and record their actual results. + +### Promotion, release and production authority + +Azusa, CEO of Logbie LLC, may approve and perform builds, releases, merges to +`main`, release promotions, tags and production deployments only when every +required check passed on the exact commit being acted on: none skipped, +missing, pending, flaky or failing. Record the SHA, required-check set and +individual result links, then recheck immediately before acting. A different +SHA or aggregate green is insufficient; a flaky rerun is not a waiver. +Anything short of fully green stops for Brad's explicit authorization. +Yomi's current-revision review and handled bot feedback remain required. + +Always Brad's decisions regardless of CI: spending money; deleting data, +agents or repositories; anything touching secrets; VM configuration changes; +and removing or weakening required checks. Release/deploy workflow changes, +organization settings/membership and deletion of branches, rulesets or +workflows also require Brad's explicit approval through the owning issue. + +Production hosts are read-only for agents: authorized config/log inspection +only, without exposing secrets. No edits, restarts, installs or migrations. +The conditional CEO production-deployment authority above is limited to the +authorized deployment; it grants no general production administration. +Other production changes go to Brad through Azusa. + +### Credentials, exceptions and enforcement + +Never commit, print, log or paste credentials into files, comments, PRs, +command arguments or remote URLs. Inject authorized tokens through environment +variables from approved storage, with minimal scope. Suspected exposure: +stop propagation, report safe metadata, and coordinate response with Brad. +Do not borrow another agent's or a human's credentials. + +Tie governed changes to an owning issue. Record exceptions with scope, reason, +risk, owner, expiry and follow-up, and obtain Brad's explicit approval before +acting. A deviation note is not approval and cannot silently amend policy. + +Policy text does not configure GitHub. Verify effective protections and actual +required checks via the API. Report missing controls, identities and platform +limits explicitly; never call a convention machine-enforced. In particular, +a shared author identity cannot supply independent GitHub approval. Deferred +identity enforcement does not authorize bypass or replace Yomi's review. + ## 1. Project identity | Item | Value | @@ -59,7 +152,7 @@ may care about. | Decision type | Who decides | Notes | |---|---|---| -| 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 | +| Day-to-day PR merge | Maintainer(s); project-run agents for eligible I1 fixes under §3.9 | Current-revision CI, Yomi review, handled bot feedback, and the LOG-16 ruleset | | 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 | @@ -164,8 +257,8 @@ and [Docs/06-best-practices/collaboration-guide.md](Docs/06-best-practices/colla - Version scheme: **YY.MM.BUILD** (e.g. `26.7.28`). Major (year) must stay **< 256** for Windows MSI compatibility. - Supported security versions are listed in [SECURITY.md](SECURITY.md). -- Maintainers cut releases; Contributors do not publish project releases unless - explicitly delegated. +- Release authority follows the common policy above: Azusa only at the + exact-commit fully-green gate; Brad otherwise. No implicit delegation. ### 3.8 Repository hygiene and layout @@ -217,12 +310,13 @@ is no automatic promotion timeline; appointments are explicit and public 2. Fork (or use a branch if you have write access) and implement with TDD. 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). + impact (canonical template: [`.github/pull_request_template.md`](.github/pull_request_template.md)). 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. + CI, review, and evidence gates pass. Main/release actions follow the + common policy's conditional CEO gate. Maintainers may reject or request changes for any reason grounded in these policies, including style that violates WFL’s natural-language design goals, diff --git a/README.md b/README.md index 5845818e..26aef71c 100644 --- a/README.md +++ b/README.md @@ -159,3 +159,9 @@ Project conventions (also binding under governance): ## License Licensed under the [Apache License 2.0](LICENSE). + +## Contribution policy + +Read [GOVERNANCE.md](GOVERNANCE.md) and [CONTRIBUTING.md](CONTRIBUTING.md). +Work on feature branches and open PRs into `dev`; current-revision CI and +Yomi review are required. diff --git a/SECURITY.md b/SECURITY.md index 65eab0e4..445c51d2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,9 @@ # Security Policy +Contribution authority, feature → `dev` PRs, exact-commit CI, Yomi review, +bot feedback, secrets and production boundaries follow +[GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27). + ## ⚠️ Alpha Software Notice **WFL is currently in alpha stage and should not be used in production environments.** This alpha status means that security features are still being developed and hardened. Use WFL only for development, testing, and educational purposes. @@ -163,9 +167,9 @@ As alpha software, WFL has the following known limitations: ### Documentation -- [WFL Architecture](Docs/technical/wfl-architecture-diagram.md) - Understanding system components -- [Error Handling](Docs/language-reference/wfl-errors.md) - Secure error management -- [Async Operations](Docs/language-reference/wfl-async.md) - Network security considerations +- [WFL Architecture](Docs/contributing/architecture-overview.md) - Understanding system components +- [Error Handling](Docs/03-language-basics/error-handling.md) - Secure error management +- [Async Operations](Docs/04-advanced-features/async-programming.md) - Network security considerations ### Security Testing @@ -201,4 +205,4 @@ We appreciate the security research community and will acknowledge responsible d **Last Updated**: September 2026 **Version**: 26.8.12 -© 2026 Logbie LLC. This security policy is subject to updates as WFL evolves from alpha to stable release. \ No newline at end of file +© 2026 Logbie LLC. This security policy is subject to updates as WFL evolves from alpha to stable release. diff --git a/testing.md b/testing.md index ecf61fa7..33f9fa62 100644 --- a/testing.md +++ b/testing.md @@ -1,5 +1,9 @@ # WFL Testing — Policy & Project Profile +Contribution authority, feature → `dev` PRs, exact-commit CI, Yomi review, +bot feedback, secrets and production boundaries follow +[GOVERNANCE.md](GOVERNANCE.md#common-contribution-policy--version-10-2026-09-27). + This repository adopts the **Logbie Testing Policy** (reproduced verbatim in [§ Logbie Testing Policy](#logbie-testing-policy) below) and defines the WFL project testing profile required by that policy's §4.