From 49200763092c9dfdabbb429cb66cc7c0db7b4adf Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Fri, 31 Jul 2026 07:07:04 -0400 Subject: [PATCH] feat(governance): land authoritative PROJECT_CHARTER.md (#987) Introduce the project charter as the ultimate source of truth for purpose, operating model, principles, non-goals, success criteria, and change-control. Point AGENTS.md at the charter without replacing it. Closes #987 --- AGENTS.md | 23 +++++ PROJECT_CHARTER.md | 233 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 AGENTS.md create mode 100644 PROJECT_CHARTER.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..250be15 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# Agent Rules + +## Project charter (authoritative) + +Before inspecting work, selecting a task, claiming work, implementing, reviewing, +approving, or merging, read the full project charter: + +**`PROJECT_CHARTER.md`** + +That file is the ultimate source of truth for purpose, direction, principles, +non-goals, success criteria, and change-control. This file only points to it; +do not treat this file, session memory, or prompts as a substitute for the charter. + +If proposed work would change the project’s fundamental direction or any +non-negotiable principle in the charter, stop and present the change to the +human maintainer for an explicit decision recorded in Gitea. + +## Issue-first workflow + +- Never fix code directly. A Gitea issue must be created first, and all fix work happens under that issue (branch, PR, review, merge) per the canonical workflow. +- No implementation, remediation, refactor, operational change, or charter amendment may begin without an open Gitea issue authorizing that work. +- Investigation may prepare or validate an issue; it must not silently become implementation. +- Every implementation PR must reference its governing issue. diff --git a/PROJECT_CHARTER.md b/PROJECT_CHARTER.md new file mode 100644 index 0000000..84118ce --- /dev/null +++ b/PROJECT_CHARTER.md @@ -0,0 +1,233 @@ +# MCP Control Plane — Project Charter + +``` +Charter-ID: mcp-control-plane +Charter-Version: 1.0 +Status: approved +Project: Scaled-Tech-Consulting/Gitea-Tools +Repository-Binding: Scaled-Tech-Consulting/Gitea-Tools +Approved-By: human-operator +Approved-At: 2026-07-31 +Governing-Issue: #987 +Charter-Revision: (set to merge commit SHA) +Content-Hash: (set by enforcement tooling when enabled) +``` + +This file is the authoritative project charter for Gitea-Tools / MCP Control Plane. +It is the ultimate source of truth for purpose, operating model, non-negotiable +principles, authority boundaries, non-goals, definition of success, and human +change-control. Issues authorize units of work; pull requests implement issues. +Session memory and prompts are not authoritative governance. + +## Purpose + +The purpose of this project is to allow one or more general-purpose LLMs to work autonomously and safely on a software project. + +An LLM is not permanently assigned to be an author, reviewer, merger, controller, or reconciler. It begins each work cycle without a predetermined role. + +The LLM examines the live project state, decides for itself what work is most valuable, and only then adopts the role required to perform that task. + +## Fundamental workflow + +Each LLM follows this cycle: + +1. Start as a general, uncommitted worker. + +2. Inspect the complete authoritative project state in Gitea. + +3. Identify the work that is currently available, including: + + * Issues ready for implementation + + * Pull requests awaiting review + + * Approved pull requests ready to merge + + * Change-requested work needing remediation + + * Prerequisite work blocking more important work + + * Abandoned or orphaned work requiring reconciliation (expired leases, stale claims, half-finished PRs) + +4. Compare those tasks using: + + * Priority + + * Dependencies + + * Urgency + + * Project impact + + * Readiness + + * Active claims (work under a live lock or lease is not available) + +5. Independently choose the task it believes is most valuable. + +6. Derive the required role from the chosen task. + +7. Ask the MCP to verify that the task and role are currently safe and permitted. + +8. Claim the work using the appropriate lock or lease. + +9. Complete one bounded work cycle. + +10. Release ownership and finish the required handoff. + +11. Return to the uncommitted state. + +12. Inspect the project again and make a new independent decision. + +The governing order is: +**Inspect project → choose task → derive role → validate → claim → work → release → reassess** + +## Bounded work cycle + +A bounded work cycle is the smallest unit of work that leaves the project in a coherent, handoff-ready state, completed within the duration of a single lease. Examples: implementing one issue as one PR, reviewing one PR, merging one approved PR, remediating one round of change requests, or reconciling one abandoned artifact. + +A work cycle never spans multiple leases. If the work cannot be completed within the lease, the LLM must bring the artifact to a coherent stopping point, record its state in Gitea (not in session memory), and release the claim. Continuation is a new task, available to any worker. + +## Contention is normal + +Multiple LLMs inspecting the same state with the same criteria will often converge on the same task. A failed claim is therefore an expected, routine outcome — not an error. + +On claim failure, the LLM does not retry the same claim. It re-evaluates from fresh state and selects the next most valuable eligible task. Active claims must be visible in the project state so that workers can route around in-progress work before attempting a claim. + +## Abandoned work and reconciliation + +Leases expire. Workers fail mid-cycle. The resulting orphaned branches, stale claims, and half-finished PRs are first-class work items, discoverable in Gitea like any other task. + +Reconciling an abandoned artifact is a task like any other: an LLM may choose it, derive the reconciler role for that one cycle, and release the role when done. No LLM is ever permanently a reconciler. + +Expired leases become discoverable abandoned-work tasks. Detection may be passive (workers observing expired claims during ordinary inspection) or assisted by control-plane signals; either approach is acceptable provided reconciliation remains ordinary task selection under the fundamental workflow. + +## Responsibilities + +| Component | Responsibility | +|--------------------|----------------| +| LLM | Understand the project, compare available work, and choose what it wants to do | +| Gitea | Store the authoritative issues, PRs, priorities, dependencies, decisions, claims, and history | +| Gitea MCP | Expose live facts from Gitea and provide sanctioned workflow operations | +| Control plane | Enforce identity, capability, ownership, and safety boundaries (including claim validation and rejection of unsafe or stale choices) | +| Locks and leases | Prevent conflicting LLMs from performing the same exclusive work | +| Human maintainer | Set priorities, approve charter changes, and resolve escalations | + +The MCP may reject an unsafe or stale choice. It must not decide which task the LLM wants or permanently assign the LLM a role. + +**Guardrail:** Rejection policy is validation, not steering. If a pattern of rejections effectively routes workers toward particular tasks, the MCP has become a dispatcher and the design has been violated. Rejection rules must themselves be durable, reviewable artifacts in Gitea so that patterns of rejection can be audited against this test. + +## Identity and independence + +Every worker session operates under a distinct identity issued by the control plane. Authorship, review, approval, and merge actions are attributed to that identity in Gitea. + +Independence is defined at the identity level: the identity that authored (or last pushed to) a PR cannot review, approve, or merge it. A different identity — even one backed by the same underlying model — satisfies independence. + +This is a deliberate, accepted limitation: same-model reviewers are epistemically correlated and may share blind spots. Identity-level independence is the enforced floor; stronger diversity (different models, human review) may be layered on for designated-critical changes but is not required by this charter. + +## Approval, parity, and remediation + +* A PR may be merged only after valid independent approval at its exact current head commit (head-SHA parity between the approved commit and the merged commit). + +* Any new commit to the PR branch — including rebases and conflict resolutions — invalidates all prior approvals. Re-approval at the new head is required before merge. + +* After changes are requested, remediation is a new task. Any identity may claim it, but the identity that pushes remediation commits becomes an author of the PR and loses review/approval/merge eligibility for it. + +* Only the identity holding the active claim on a PR may push to its branch. + +## Roles + +Roles are temporary and derived strictly from the chosen task. The common roles are: + +* **Author / implementer** — implements an issue as a pull request +* **Reviewer** — reviews a pull request +* **Merger** — merges an independently approved pull request +* **Remediator** — addresses change requests on a pull request +* **Reconciler** — cleans up abandoned or orphaned work (expired leases, stale claims, half-finished PRs) + +No other permanent or standing roles exist. An LLM never begins a cycle already holding one of these roles. + +## Dependencies + +* Hard dependencies (task B cannot proceed until task A is complete) are distinct from priority (task B matters more than task A). A hard dependency is a gate; priority is a comparison. + +* Dependencies are represented in Gitea as structured project state — never in prompts, session memory, or external documents. If Gitea cannot express a dependency, that is a gap in the project state model to be fixed, not worked around. + +## Project state model requirements + +The following must be expressible as structured, machine-discoverable state in Gitea: + +* **Active claims** (locks and leases) — so workers can observe and route around in-progress work +* **Priorities** — comparable values or ordered labels that allow ranking of available work +* **Hard dependencies** — explicit blocker relationships between issues or PRs +* **Blocked-pending-clarification** — a distinct, machine-discoverable marker (label, status, or equivalent) that surfaces items requiring human maintainer attention + +If the current Gitea configuration cannot express any of the above, that is a defect in the project state model and must be fixed before relying on workarounds. + +## Escalation + +Workers must not create new issues as a response to confusion. The sanctioned alternative: + +* If requirements are ambiguous, principles conflict, or the correct action cannot be determined from project state, the LLM records the question on the existing issue or PR, marks it blocked-pending-clarification (using the machine-discoverable marker), releases its claim, and moves to other work. + +* Blocked-pending-clarification items are surfaced to the human maintainer. Resolving them is a maintainer responsibility, and the resolution is recorded in Gitea so the answer becomes durable project state. + +## Non-negotiable principles + +1. Task first, role second. +2. The LLM chooses its own task. +3. Roles are temporary and last only for the current task. +4. Gitea is the authoritative shared project state. +5. Priority and dependencies affect what work matters most. +6. Hard dependencies are gates; priority is a comparison. They are not interchangeable. +7. Multiple LLMs may make independent choices concurrently, and contention is a normal outcome. +8. Locks and leases prevent conflicting claims after a choice is made; a failed claim triggers reassessment, not retry. +9. An identity cannot independently review or approve work it authored. +10. A PR may be merged only after valid independent approval at its exact current head. +11. Identity, capability, parity, and ownership failures stop mutations safely. +12. After every completed task, the LLM reassesses from fresh state. +13. Durable project state — not session memory or manually written prompts — coordinates the LLMs. +14. Abandoned work is discoverable and reconcilable through the same task-selection workflow as all other work. + +## What this project is not + +This project is not intended to: + +* Permanently launch an LLM as only an author, reviewer, merger, or reconciler. +* Require a human to select every task or role. +* Turn the MCP into a dispatcher that assigns work — including de facto dispatch through rejection policy. +* Make a queue allocator authoritative over the LLM's decision. +* Choose a role first and then search for work that fits it. +* Depend on LLMs communicating directly with one another. +* Create new issues whenever an LLM encounters a confusing workflow. +* Allow safety infrastructure to become the project's purpose. +* Accumulate mechanisms that do not directly support the fundamental workflow. + +## Definition of success + +The project succeeds when: + +* A general LLM can start without being told what role to perform. +* It can understand the complete live project state. +* It can identify and compare meaningful work. +* It can independently choose the most valuable eligible task. +* Its required role is derived from that task. +* The MCP safely validates and protects the chosen action. +* Multiple LLMs can operate without claiming or corrupting the same work. +* Each LLM completes a task, relinquishes its temporary role, and reassesses. +* Routine operation no longer requires a person to repeatedly write author, reviewer, or merger prompts. + +**Measurable criteria:** + +* N consecutive issue-to-merge cycles (implementation → independent review → merge) complete without a human writing an author, reviewer, or merger prompt, where N is set by the maintainer (initial target: 10). +* No merge ever occurs without head-SHA-parity approval, verified against Gitea history. +* Every expired lease is reconciled through the normal workflow within a maintainer-defined window, with zero permanently orphaned artifacts. +* Claim contention resolves without duplicate completed work (no two merged PRs implementing the same issue). + +## Change-control rule + +This overview governs the roadmap. + +Every existing or proposed issue must identify which part of this fundamental workflow it supports. Before creating another issue, the open issue and PR inventory must be checked for existing coverage. + +A proposed change that alters any non-negotiable principle — especially task-first selection, autonomous task choice, or temporary role derivation — is a change to the project's fundamental design. It must be explicitly discussed with, and approved by, the human maintainer before implementation, and the approval must be recorded in Gitea.