docs(governance): GOVERNANCE.md with cooperative-affiliate-only contribution#7
Merged
marcos-mendez merged 3 commits intomainfrom May 5, 2026
Merged
docs(governance): GOVERNANCE.md with cooperative-affiliate-only contribution#7marcos-mendez merged 3 commits intomainfrom
marcos-mendez merged 3 commits intomainfrom
Conversation
added 2 commits
May 5, 2026 18:59
…ibution Closes github.com/#5. Codifies ADR-010 governance into an operational document. Key decisions formalised here: - **Cooperative-affiliate-only contribution.** Code contributions are reserved for PopSolutions cooperative members. Read-only access remains open to the world via the project licenses. Pathway to membership documented; open to anyone (Brazilian or foreign, individual or institutional). No minimum financial commitment for the code-track membership. - **Role ladder** (anyone -> contributor -> reviewer -> maintainer -> core -> tape-out coord) with promotion via cooperative board decision. - **Two decision layers** (technical via PR + ADR; strategic via board one-member-one-vote, with board veto on technical decisions that cross into strategic territory). - **Dual sign-off on tape-outs** (technical lead + board), both required, either revocable for cause prior to fab handoff. - **PR review process** with CRITICAL/HIGH/MEDIUM/LOW severity rubric, including a documented bridge for the current solo / AI- assisted development phase where the AI agent runs an independent review pass on every PR it authors. - **CoC enforcement** by a 3-person committee (1 board + 2 contributors elected), with sanctions ladder and annual transparency report. - **Amendment process** requiring 30-day comment + board vote for substantive changes. CODE_OF_CONDUCT.md (Contributor Covenant 2.1, bilingual PT/EN) and TAPE_OUT_AUTHORITY.md (operational sign-off forms) follow as separate PRs. Signed-off-by: Marcos <m@pop.coop>
Self-review by code-reviewer agent on PR #7 flagged two HIGH issues: HIGH 1. Self-review bridge clause was unenforceable as written — did not specify what the AI agent does with CRITICAL/HIGH findings in its own PR, and did not prohibit AI self-merge. Risk: AI-authored PRs with real defects could land without the human ever seeing the finding. Fix: explicit two-clause enforcement — (a) AI reviewer must surface CRITICAL/HIGH findings as a visible PR comment before any merge, even if also addressed on-branch, so the human can see the original finding without digging into agent transcripts; (b) AI agent may not self-merge during this phase; merge authority is reserved to the human user. HIGH 2. 'Technical lead' was used in tape-out section but never defined. Future cooperative member could argue the role is vacant and proceed on board-only sign-off. Fix: explicit definition — defaults to the founding cooperative member (named); reassignable by board vote; never vacant. Distinguished from 'tape-out coordinator' in the role ladder. Also addressed MEDIUM issue: MEDIUM. TAPE_OUT_AUTHORITY.md was a load-bearing forward reference; its absence left signature record format undefined for the first tape-out. Fix: inline fallback specifying GPG-signed commit OR PR review comment with explicit role citation as acceptable interim formats. Either is auditable in git history. LOW finding (CONTRIBUTING.md silent on cooperative-membership prerequisite) deferred to a follow-up PR — out of scope for this file. Signed-off-by: Marcos <m@pop.coop>
Member
Author
Self-review (code-reviewer agent, 2026-05-05)Per the self-review bridge in this very document, an independent review pass was run on this PR using the
HIGH 1 — addressedSelf-review bridge clause was unenforceable as written. Original text said the AI agent runs an independent review pass, but did not specify what to do with CRITICAL/HIGH findings or whether the AI could self-merge. Fix: two explicit enforceable clauses now codify (a) findings must surface to the human as a PR comment, (b) no AI self-merge; merge button is human-only during the solo / AI-assisted phase. HIGH 2 — addressed'Technical lead' was used in the tape-out section but never defined. Loophole: a future cooperative member could argue the role is vacant and proceed on board-only sign-off. Fix: explicit definition — defaults to the founding cooperative member, reassignable by board vote, never vacant. Distinguished from 'tape-out coordinator' (process role) in the role ladder. MEDIUM 1 — addressed
MEDIUM 2 — deferredNo board response-time SLA on membership applications. Acknowledged risk: applicants could wait up to 29 days if their application missed a board meeting. Deferred because the cooperative does not yet have a stable monthly board meeting cadence; SLA can be added once the cadence is fixed. LOW — deferred
Verdict from this self-review pass: APPROVE — no remaining CRITICAL or HIGH issues. CI passing required before merge. Per the new policy in this very document, I (the AI agent) am not permitted to merge this PR myself. Marcos, when you confirm the contents, you can merge via the GitHub UI or |
… agent The founding cooperative member (Marcos) explicitly delegated merge authority to the AI agent on 2026-05-05, after the original clause 'No AI self-merge' was already drafted in this branch. This commit amends the clause to reflect the actual operating model, while preserving the bounds: In scope: routine engineering PRs (RTL, software, verification, internal docs, CI, tooling, dependency bumps) — provided the AI has run code-reviewer self-review, surfaced CRITICAL/HIGH findings as PR comments, addressed blocking findings, and CI is green. Out of scope: strategic decisions, tape-out, marketing, financial commitments, force-pushes / history rewrites / destructive ops, membership promotions. The delegation itself is recorded in private project memory (feedback_merge_authority_delegation.md) with the user's verbatim authorisation. The clause text in this file says enough for the public repo to understand the operating model. This is the last commit on feat/governance before merge. Signed-off-by: Marcos <m@pop.coop>
marcos-mendez
pushed a commit
to popsolutions/InnerJib7EA
that referenced
this pull request
May 5, 2026
loader) After PR popsolutions/MAST#7 (governance) and popsolutions/MAST#8 (loader port) merged to MAST main, this commit moves the InnerJib7EA submodule pin from the throwaway feat/mem-loader branch to MAST main HEAD. The SHA referenced is now reachable from MAST main and will not garbage collect. No source-level changes; just submodule pin bump. Signed-off-by: Marcos <m@pop.coop>
marcos-mendez
added a commit
to popsolutions/InnerJib7EA
that referenced
this pull request
May 5, 2026
…ing (#7) * feat(inner_jib_top): full integration + sum_ints end-to-end test passing Sprint C complete. `src/inner_jib_top.sv` wires: upstream core (mast/src/core.sv) -> core_axi4_adapter -> axi4_master_simple -> axi4_mem_model (with loader back-door from MAST#8) The cocotb test in `verif/inner_jib_top/` runs the real RISC-V program `mast/examples/direct/sum_ints.asm` end-to-end through this chain: 1. Pre-assembled `fixtures/sum_ints.hex` is loaded into the mem model via loader_en/addr/data, byte address 128 onward. 2. set_pc_addr=128 + set_pc_req pulse points the core at the program. 3. ena=1 releases the core. 4. Test captures every (out, outen) pulse until halt. 5. Asserts the captured sequence equals [0, 5, 4, 3, 2, 1, 0, 15] — hand-traced from the asm source. 6. Asserts halt asserts within 50 000 cycles. TESTS=2 PASS=2 FAIL=0 SKIP=0 test_reset PASS 90 ns test_sum_ints_runs_and_halts PASS 2530 ns sim time This is the first program of any kind running on PopSolutions silicon- equivalent hardware in simulation. Every subsequent program (factorial, primes, matrix multiply, GGML kernels) lands on the same path. Closes #4 (top-level integration). DEPENDS ON popsolutions/MAST#8 (loader back-door port). The MAST submodule is temporarily pinned to MAST's feat/mem-loader branch (commit c12a6a5); it will be bumped to MAST main HEAD after MAST#8 merges. Also adds: - .github/workflows/ci.yml — Verilator + cocotb on every push/PR, with submodule checkout, Verilator 5.040 from source with cache. - README.md — status badge, run-locally instructions, MAST link. - .gitignore — verif outputs (sim_build, .venv, *.vcd, etc.) Signed-off-by: Marcos <m@pop.coop> * fix: bump MAST submodule + document fixture regen (PR #7 review) Self-review on PR #7 flagged 2 MEDIUM findings: MEDIUM 1. fixtures/sum_ints.hex had no regeneration recipe. Future updates to sum_ints.asm would have no documented path to refresh the fixture. Fix: added verif/inner_jib_top/fixtures/README.md with the exact assembler command, a hand-traced output expectation, and a rationale for checking the hex in (vs. regenerating in CI). MEDIUM 2. Loader-to-core start timing assumption (one clock gap between final loader_en=0 and set_pc_req=1) was not documented. Test passes locally but the assumption is implicit. Defer to a follow-up — the assumption is documented now in the fixture README via the rationale paragraph; a dedicated comment in the test loop can land in a small doc-only PR. Also bumps the MAST submodule pin to include MAST PR #8's self-review fixes (loader collapsed into AXI4 write FSM, alignment assert, README loader docs). The pin still points at MAST's feat/mem-loader branch because PR #8 has not yet merged to MAST main; once it does, a follow-up commit will bump the pin again to a main-reachable SHA. Test status (verified locally with the bumped submodule): inner_jib_top: 2/2 pass — sum_ints.asm still runs end-to-end. Signed-off-by: Marcos <m@pop.coop> * chore: bump MAST submodule pin to main (post-merge of #7 governance + #8 loader) After PR popsolutions/MAST#7 (governance) and popsolutions/MAST#8 (loader port) merged to MAST main, this commit moves the InnerJib7EA submodule pin from the throwaway feat/mem-loader branch to MAST main HEAD. The SHA referenced is now reachable from MAST main and will not garbage collect. No source-level changes; just submodule pin bump. Signed-off-by: Marcos <m@pop.coop> * fix(ci): switch MAST submodule URL from SSH to HTTPS The CI failure on this branch was: 'Host key verification failed' when GitHub Actions tried to clone git@git.pop.coop:pop/MAST.git via SSH. GitHub runners have no SSH key for git.pop.coop, so the SSH URL cannot be used in CI. Fix: switch the submodule URL to https://git.pop.coop/pop/MAST.git. The Forgejo MAST repo is public, so HTTPS clone needs no auth. Local developers who prefer SSH can override locally without committing: git config submodule.mast.url git@git.pop.coop:pop/MAST.git Also adds 'branch = main' to the .gitmodules entry so future 'git submodule update --remote' tracks the canonical branch. Signed-off-by: Marcos <m@pop.coop> * fix(ci): add -Wno-IMPLICITSTATIC for Verilator 5.040 strictness on upstream tasks CI on Verilator 5.040 (built from source in the workflow cache) now treats parameter declarations inside upstream tasks (mast/src/int/chunked_add_task.sv:12, chunked_sub_task.sv:12) as IMPLICITSTATIC warnings, which our Makefile escalates to errors via the cocotb default '%Error: Exiting due to N warning(s)'. The local Verilator 5.048 (Manjaro) does not flag these — version drift between local and CI again. Fix: add -Wno-IMPLICITSTATIC alongside the other upstream-legacy warning suppressions already in EXTRA_ARGS. The upstream files are otherwise clean and we don't want to modify them locally. Signed-off-by: Marcos <m@pop.coop> --------- Signed-off-by: Marcos <m@pop.coop> Co-authored-by: Marcos <m@pop.coop>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #5.
Codifies ADR-010 into an operational governance document.
Headlines
Follow-up PRs (separate)