Team Governance

Two-layer scope hierarchy with conflict detection and amendment workflows. Enforce team standards while allowing individual developers flexibility.

The two scopes

Scope	Who owns it	Override rules
Team	The whole engineering team	Cannot be overridden by individual decisions without an approved amendment
Individual	A single developer	Can extend team decisions; cannot contradict them

Recording a team-level decision

Team decisions are recorded by first creating a team scope (if one doesn't exist) and then logging a governance rule under that scope. Any AI with access to the Engrams MCP server will enforce the rule automatically from that point forward.

You: "Record a team decision: all data storage must use PostgreSQL.
       This is a hard block — no exceptions without a formal amendment."

AI:  I'll create a team scope and record that as a governance rule.

     Scope created: "Core Architecture" (team)
     Governance rule logged:
       Rule #23 — "Standardize on PostgreSQL for all data storage"
       Scope: Core Architecture (Team-level)
       Enforcement: hard_block
       Tags: database, architecture

     Any proposal that conflicts with this rule will be blocked until
     the team approves a formal amendment.

Under the hood this calls create_scope (once, if the scope is new) and then log_governance_rule with the chosen enforcement level.

Enforcement levels

Every governance rule carries one of three enforcement levels. Choose the level that matches how strictly the rule should be applied.

Level	What the AI does	When to use it
`hard_block`	Stops the work entirely and requires an explicit amendment before proceeding.	Non-negotiable standards — security policies, licensing requirements, core architecture mandates.
`soft_warn`	Raises a visible warning and asks for acknowledgement, but allows the developer to proceed.	Strong preferences the team usually follows but that may have legitimate exceptions (e.g. preferred libraries, naming conventions).
`allow_with_flag`	Permits the action and silently records a flag in the context so the deviation is visible in reviews and reports.	Advisory guidelines or emerging best practices where awareness matters but blocking would be counterproductive.

hard_block example

You: "Record a team rule: never store credentials in source code.
       Enforcement: hard_block."

AI:  Governance rule logged:
     Rule #7 — "No credentials in source code"
     Scope: Security (Team-level)
     Enforcement: hard_block

---

You: "Add the DB password directly to config.py for now."

AI:  ⛔ Governance Conflict — hard_block

     Rule #7: "No credentials in source code"
     Scope: Security (Team-level)

     This action is blocked. Please use environment variables or a
     secrets manager. Would you like to propose a formal amendment?

soft_warn example

You: "Record a team rule: prefer React Query for all server-state fetching.
       Enforcement: soft_warn."

AI:  Governance rule logged:
     Rule #14 — "Prefer React Query for server-state management"
     Scope: Frontend (Team-level)
     Enforcement: soft_warn

---

You: "Fetch the user list with useEffect and useState."

AI:  ⚠️ Governance Advisory

     Rule #14: "Prefer React Query for server-state management"

     The team prefers React Query here. Proceeding with useEffect/useState
     is allowed, but consider refactoring later. Continue anyway?

allow_with_flag example

You: "Record a team guideline: prefer named exports over default exports.
       Enforcement: allow_with_flag."

AI:  Governance rule logged:
     Rule #31 — "Prefer named exports"
     Scope: Code Style (Team-level)
     Enforcement: allow_with_flag

---

You: "Add a default export to this utility module."

AI:  (Proceeding — deviation from Rule #31 "Prefer named exports" has been
     flagged in the active context for visibility in code review.)

Pre-mutation decision check

Before making any changes, your AI should verify the planned action against existing team decisions using tool_check_planned_action. This is a lightweight pre-check that runs before any code is written.

You: "I want to use MongoDB for the analytics module"

AI:  [Checking planned action against team decisions...]

     ⛔ Conflict detected with Decision #23:
     "Standardize on PostgreSQL for all data storage"

     This decision is marked as a team-level hard block.
     I cannot proceed without a formal amendment.
     Would you like to propose one?

The pre-check is part of the defense-in-depth governance system:

Pre-mutation — tool_check_planned_action checks against accepted team decisions before any work
Post-write — check_compliance verifies items against scope rules after they are saved

Even if the pre-check is skipped, the post-write safety net still flags conflicts. Both layers work together to prevent accidental violations of team standards.

Conflict detection (post-write)

You: "I want to use MongoDB for the analytics module"

AI:  Governance Conflict Detected

     Your proposal conflicts with Team Decision #23:
     "Standardize on PostgreSQL for all data storage"
     Scope: Core Architecture (Team-level)

     This is a hard block. Would you like to propose an amendment?

Amendment workflow

You: "Propose an amendment to allow InfluxDB for time-series metrics"

AI:  Amendment proposal created:
     Amendment #2 to Decision #5
     Proposal: Allow InfluxDB for time-series metrics data
     Rationale: PostgreSQL isn't optimized for high-volume time-series
     Status: Pending team review

Individual strategies

You: "When I say I'm ready to create a PR, compare my branch with main
      and generate a succinct summary for the PR description. Then run
      autoflake and npm run lint -- --fix."

AI:  Individual strategy #4 created:
     Code summarization, import cleanup, and JS linting on PR creation.

Effective context

get_effective_context merges team and individual decisions, applying the correct precedence rules. Your AI always sees the right combined view.

Team sync via Git

Governance decisions with visibility=team are automatically written to the .engrams/decisions/ directory as human-readable markdown files. Commit them to Git and every teammate receives the architectural mandates on their next pull.

See Team Sync for the full filesystem-first architecture and setup guide.

MCP tools

tool_check_planned_action — pre-mutation check against accepted team decisions
create_scope / get_scopes
log_governance_rule / get_governance_rules
check_compliance — post-write compliance verification
get_scope_amendments / review_amendment
get_effective_context