From 03bccfeeaec466f80c681b8b8c78f28f3f895894 Mon Sep 17 00:00:00 2001 From: Sawako Yamanaka Date: Sun, 27 Sep 2026 08:26:32 +0000 Subject: [PATCH 1/2] ci: run existing checks for dev pull requests Co-Authored-By: Paperclip --- .github/workflows/ci.yml | 2 +- .github/workflows/wfl-config-lint.yml | 2 +- 2 files changed, 2 insertions(+), 2 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 From 0bc00fef6e32790a5fd53ee908dccaec70d48d69 Mon Sep 17 00:00:00 2001 From: Sawako Yamanaka Date: Sun, 27 Sep 2026 13:53:25 +0000 Subject: [PATCH 2/2] docs: harmonize governance and contribution authority Co-Authored-By: Paperclip --- .github/pull_request_template.md | 25 +++++ AI_POLICY.md | 7 +- CLAUDE.md | 5 + CONTRIBUTING.md | 9 +- Docs/06-best-practices/collaboration-guide.md | 6 ++ Docs/contributing/contributing-guide.md | 5 +- GOVERNANCE.md | 94 ++++++++++++++++++- README.md | 6 ++ SECURITY.md | 13 ++- testing.md | 5 + 10 files changed, 162 insertions(+), 13 deletions(-) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..4e7263c94 --- /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/AI_POLICY.md b/AI_POLICY.md index af63df120..a72ad54bd 100644 --- a/AI_POLICY.md +++ b/AI_POLICY.md @@ -1,5 +1,10 @@ # 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.** @@ -112,7 +117,7 @@ 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 +- Yomi review and the dev/CEO/Brad authority gates in [GOVERNANCE.md](GOVERNANCE.md) on merges and releases --- diff --git a/CLAUDE.md b/CLAUDE.md index 869ee11b1..042547619 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,10 @@ # 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 d047d1823..dee39865d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,10 @@ # 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 @@ -33,10 +38,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 bca904c29..6385373fa 100644 --- a/Docs/06-best-practices/collaboration-guide.md +++ b/Docs/06-best-practices/collaboration-guide.md @@ -270,3 +270,9 @@ You've completed the Best Practices section. You now know how to write quality W --- **Previous:** [← Project Organization](project-organization.md) | **Next:** [Guides →](../guides/) + +## Repository contribution authority + +Follow [GOVERNANCE.md](../../GOVERNANCE.md) for feature → `dev` PRs, +Yomi review, exact-commit Actions evidence, bot feedback and promotion authority. +Use the [canonical PR checklist](../../.github/pull_request_template.md). diff --git a/Docs/contributing/contributing-guide.md b/Docs/contributing/contributing-guide.md index e35c668eb..9bf679f40 100644 --- a/Docs/contributing/contributing-guide.md +++ b/Docs/contributing/contributing-guide.md @@ -17,10 +17,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). diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 64fd49059..cd9a2702e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -14,10 +14,95 @@ 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 dev +merge and CEO delegations of 2026-09-26. 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. + The PR author, including an agent author, may merge their own PR into `dev` + only after applicable CI passes on that reviewed revision and findings are + addressed. This delegation needs no separate per-PR Brad 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 | @@ -58,7 +143,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 dev PR merge | PR author under the common policy above | Current-revision CI, Yomi review and handled bot feedback required | | 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 | @@ -163,8 +248,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 @@ -209,7 +294,8 @@ is no automatic promotion timeline; appointments are explicit and public 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. +6. The authorized dev PR author merges only under the common policy above; + main/release actions follow its 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 5845818ec..26aef71c5 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 65eab0e40..c02e5a523 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,10 @@ # 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 +168,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 +206,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 ecf61fa7a..ea3c24d58 100644 --- a/testing.md +++ b/testing.md @@ -1,5 +1,10 @@ # 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.