feat(governance): require an authoritative project charter for every managed project #987

New Issue

2026-07-31T06:05:41-05:00

jcwalker3 commented

2026-07-31 06:05:41 -05:00

Summary

Every software project managed through this system must contain an approved project charter that serves as the ultimate source of truth for the project’s purpose, direction, governing principles, and definition of success.

The charter must be reviewed before an LLM selects or performs work. If proposed work would change the project’s fundamental direction, the LLM must stop and present the change to a human operator for a decision.

This requirement also preserves the project rule that no implementation or operational change begins without an issue.

In scope for Gitea-Tools (this repository) — first landing

Land and approve the canonical PROJECT_CHARTER.md at the repository root (operator draft with required metadata).
Point AGENTS.md at the charter without duplicating or replacing it.
Follow-up (child issues as needed): MCP charter-acknowledgement gate, launcher startup requirements, multi-project enforcement.

Problem

Implementation details, individual issues, and workflow mechanisms can gradually steer a project away from its original purpose. An LLM may optimize a local task without recognizing that the task conflicts with the project’s fundamental goal.

Session memory, prompts, issue titles, and implementation documentation are not reliable substitutes for an authoritative governing document.

Without a charter:

LLMs can lose the project’s original purpose.
Infrastructure mechanisms can be mistaken for the project’s goal.
New issues can expand the architecture without strategic justification.
Different LLMs can operate from different interpretations of the project.
Fundamental direction can change incrementally without an explicit human decision.
An issue or PR can be technically correct while moving the project in the wrong direction.

Governing model

Each managed project must have a canonical charter stored at the repository root:

PROJECT_CHARTER.md

The charter is the ultimate source of truth for project purpose, operating model, non-negotiable principles, authority boundaries, non-goals, definition of success, and human change-control.

Gitea remains the authoritative execution record for issues, PRs, reviews, merges, and history.

No-work-without-an-issue rule

No implementation, remediation, refactor, operational change, or charter amendment may begin without an open Gitea issue authorizing and defining that work.

Investigation may prepare or validate an issue; it must not silently become implementation. Every implementation PR must reference its governing issue. The charter itself may be introduced or amended only through a dedicated issue and a separately reviewable charter change.

Required charter metadata

Each charter must identify at least: Charter ID, version, status, project/repository binding, approval authority, approval date, charter revision or commit SHA, and content hash when used by enforcement.

Mandatory LLM startup behavior

Before work selection or mutation, an LLM must resolve the project, retrieve and read the canonical charter from the default branch, acknowledge the exact version/revision/hash, and confirm intended activity is governed by that charter. AGENTS.md may point to the charter but must not replace it.

MCP enforcement (follow-up)

The MCP/control plane should provide a charter acknowledgement gate bound to repository identity, charter version/revision/hash, and trusted client-instance identity, failing closed until acknowledgement is recorded.

## Summary Every software project managed through this system must contain an approved project charter that serves as the ultimate source of truth for the project’s purpose, direction, governing principles, and definition of success. The charter must be reviewed before an LLM selects or performs work. If proposed work would change the project’s fundamental direction, the LLM must stop and present the change to a human operator for a decision. This requirement also preserves the project rule that no implementation or operational change begins without an issue. ## In scope for Gitea-Tools (this repository) — first landing - Land and approve the canonical `PROJECT_CHARTER.md` at the repository root (operator draft with required metadata). - Point `AGENTS.md` at the charter without duplicating or replacing it. - Follow-up (child issues as needed): MCP charter-acknowledgement gate, launcher startup requirements, multi-project enforcement. ## Problem Implementation details, individual issues, and workflow mechanisms can gradually steer a project away from its original purpose. An LLM may optimize a local task without recognizing that the task conflicts with the project’s fundamental goal. Session memory, prompts, issue titles, and implementation documentation are not reliable substitutes for an authoritative governing document. Without a charter: - LLMs can lose the project’s original purpose. - Infrastructure mechanisms can be mistaken for the project’s goal. - New issues can expand the architecture without strategic justification. - Different LLMs can operate from different interpretations of the project. - Fundamental direction can change incrementally without an explicit human decision. - An issue or PR can be technically correct while moving the project in the wrong direction. ## Governing model Each managed project must have a canonical charter stored at the repository root: `PROJECT_CHARTER.md` The charter is the ultimate source of truth for project purpose, operating model, non-negotiable principles, authority boundaries, non-goals, definition of success, and human change-control. Gitea remains the authoritative execution record for issues, PRs, reviews, merges, and history. ## No-work-without-an-issue rule No implementation, remediation, refactor, operational change, or charter amendment may begin without an open Gitea issue authorizing and defining that work. Investigation may prepare or validate an issue; it must not silently become implementation. Every implementation PR must reference its governing issue. The charter itself may be introduced or amended only through a dedicated issue and a separately reviewable charter change. ## Required charter metadata Each charter must identify at least: Charter ID, version, status, project/repository binding, approval authority, approval date, charter revision or commit SHA, and content hash when used by enforcement. ## Mandatory LLM startup behavior Before work selection or mutation, an LLM must resolve the project, retrieve and read the canonical charter from the default branch, acknowledge the exact version/revision/hash, and confirm intended activity is governed by that charter. `AGENTS.md` may point to the charter but must not replace it. ## MCP enforcement (follow-up) The MCP/control plane should provide a charter acknowledgement gate bound to repository identity, charter version/revision/hash, and trusted client-instance identity, failing closed until acknowledgement is recorded.

jcwalker3 added the type:feature status:ready labels 2026-07-31 06:05:42 -05:00

jcwalker3 referenced this issue from a commit

2026-07-31 06:07:07 -05:00

feat(governance): land authoritative PROJECT_CHARTER.md (#987)

jcwalker3 referenced a pull request that will close this issue

2026-07-31 06:07:27 -05:00

feat(governance): land authoritative PROJECT_CHARTER.md (Closes #987) #988

jcwalker3 added status:pr-open and removed status:ready labels 2026-07-31 06:07:28 -05:00

sysadmin referenced this issue

2026-07-31 06:08:46 -05:00

feat(governance): land authoritative PROJECT_CHARTER.md (Closes #987) #988

sysadmin referenced this issue