Cedar Factory Authorization Standard

Controlling Principle: Bluefly separates descriptive agent role prompts from deterministic machine authorization. Gas City orchestrates what work exists and where it runs; Cedar policy engines decide whether a proposed mutation is authorized before execution occurs.

---

1. Three-Layer Operating Model

The Bluefly Digital Factory enforces governance across three distinct layers:

+-------------------------------------------------------------------------+
|                         1. ENGINEERING STANDARD                         |
|                 "What Bluefly's rules are and why"                      |
|                  Human & Agent Executive Doctrine                       |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                           2. CEDAR POLICIES                             |
|              "What operations are mechanically allowed"                 |
|             Deterministic Policy Decision Point (PDP)                   |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                             3. GAS CITY                                 |
|            "What work gets orchestrated and who executes it"            |
|              Orchestration PDP/PEP Enforcement Points                   |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
|                         4. EXECUTION SYSTEMS                            |
|             GitLab  *  Oracle  *  1Password  *  Beads  *  Drupal       |
+-------------------------------------------------------------------------+

1. Engineering Standard (BluCity-Docs): Canonical, human-readable authority on doctrine, roles, boundaries, and priorities.
2. Cedar Policies (cedar_policies): Machine-parsable, schema-validated authorization rules enforcing deterministic Allow | Deny decisions at mutation boundaries.
3. Gas City (BluCity): Native orchestration runtime selecting workers, dispatching formulas, handling orders, and enforcing Cedar policy decisions prior to execution.
4. Execution Systems: Targeted platforms (GitLab, Oracle, 1Password, Beads, Drupal) receiving only pre-authorized mutations.

---

2. Decoupling Advisory Prompts from Deterministic Authorization

Agent prompts (OpenCode, Gas City, system prompts) provide descriptive instructions guiding how AI models reason and plan. Prompts are advisory. They cannot provide security or governance guarantees.

Cedar policies provide deterministic machine authorization. Every mutation request is evaluated against Cedar rules before disk, git, network, or process mutations take effect.

PROMPT RULE (Advisory):  MAYOR must not author tracked source code.
CEDAR POLICY (Enforced): forbid (
                            principal is Bluefly::Agent,
                            action in [ Bluefly::Action::"ModifySource", Bluefly::Action::"CommitSource" ],
                            resource is Bluefly::Repository
                         ) when { principal.role == "mayor" };

If an agent model forgets or bypasses a prompt instruction, the Cedar gate denies the operation at runtime (DECISION=DENY).

---

3. Cedar PDP / PEP Integration Pattern

Gas City handles orchestration and dispatch; Cedar handles policy evaluation. Cedar is integrated as a thin Policy Enforcement Point (PEP) gate around Gas City commands, formulas, orders, git hooks, and deployment workflows.

   Gas City Order / Formula / Step
                 |
                 v
   Worker Proposes Action Request
                 |
                 v
   PEP Gate (blu policy authorize / CLI)
                 |
                 v
   Cedar Evaluator (PDP Engine)
                 |
        +--------+--------+
        |                 |
        v                 v
     ALLOW              DENY
        |                 |
        v                 v
   Execute Mutation    Stop + Record Evidence + Route Blocker
        |
        v
   Bead Transition / Evidence Receipt

Authorization Gate Request Interface

blu policy authorize \
  --principal Agent::"refinery" \
  --action Action::"MergeToRelease" \
  --resource Repository::"blueflyio/cedar-policies" \
  --context '{"target_branch":"release/v0.1.x","pipeline_passed":true,"unresolved_discussions":0,"conflicts":false,"bead":"cp-vc0"}'

Evaluation Output Format

{
  "decision": "ALLOW",
  "determining_policies": ["policy-git-release-004"],
  "reasons": ["Permitted merge to release/v0.1.x for passing CI pipeline and clear discussions."]
}

---

4. Factory Cedar Entity Schema

The cedar_policies repository maintains the canonical schema (schema/bluefly-factory.cedarschema).

4.1 Principals

Cedar principal identities are distinct from role attributes to preserve policy precision: - Bluefly::Agent (e.g. Agent::"blu", Agent::"mayor", Agent::"refinery", Agent::"drupal", Agent::"forge", Agent::"witness", Agent::"sentinel", Agent::"harbormaster") - Bluefly::Human (e.g. Human::"thomas") - Bluefly::ServiceIdentity (e.g. ServiceIdentity::"gitlab-service-account") - Bluefly::CIIdentity (e.g. CIIdentity::"gitlab-runner")

Principal entity attributes include: role, rig, machine_identity, trust_level.

4.2 Resource Types

Repository, Branch, MergeRequest, Release, Runtime, City, Rig, Bead, SecretReference, PolicySet, Package, Deployment, Worktree.

4.3 Action Groups & Typed Actions

Action groups organize permissions logically:

Action Group	Included Typed Actions
SourceRead	ReadSource, ReadGitHistory, InspectWorktree
SourceWrite	ModifySource, CommitSource, PushBranch, DeleteBranch
ReleaseMutation	OpenMR, MergeToRelease, PromoteToMain, PublishPackage, PublishRelease
RuntimeRead	ReadRuntime, InspectPod, ReadLog
RuntimeWrite	MutateRuntime, DeployRuntime, RestartService
WorkGraphRead	ReadBead, InspectConvoy
WorkGraphWrite	CreateBead, ClaimBead, UpdateBead, CloseBead
SecurityMutation	ResolveSecret, ModifyPolicy, GrantPermission

---

5. Master Team Directive as Cedar Policy

The Bluefly Master Team Directive (agent-team.md) is codified as executable Cedar policies:

5.1 MAYOR Authority Scope

// MAYOR may operate and mutate Oracle runtime
permit (
    principal is Bluefly::Agent,
    action in [ Bluefly::Action::"ReadRuntime", Bluefly::Action::"MutateRuntime" ],
    resource is Bluefly::Runtime
) when { principal.role == "mayor" && resource.environment == "oracle" };

// MAYOR is forbidden from modifying or committing source code
forbid (
    principal is Bluefly::Agent,
    action in [ Bluefly::Action::"ModifySource", Bluefly::Action::"CommitSource" ],
    resource is Bluefly::Repository
) when { principal.role == "mayor" };

5.2 WITNESS Read-Only Audit Scope

// WITNESS is strictly forbidden from all mutations
forbid (
    principal is Bluefly::Agent,
    action in Bluefly::ActionGroup::"Mutation",
    resource
) when { principal.role == "witness" };

5.3 DRUPAL Runtime Isolation

// DRUPAL agent cannot mutate Oracle production runtime directly
forbid (
    principal is Bluefly::Agent,
    action == Bluefly::Action::"MutateRuntime",
    resource is Bluefly::Runtime
) when { principal.role == "drupal" && resource.environment == "oracle" };

5.4 FORGE Dependency Acceptance Law

// FORGE cannot certify consumer builds containing local path or symlink repos
forbid (
    principal is Bluefly::Agent,
    action == Bluefly::Action::"CertifyConsumerBuild",
    resource is Bluefly::Package
) when {
    principal.role == "forge" &&
    (context.path_repository_used || context.local_symlink_used || context.unpublished_dependency)
};

5.5 Git Release & Promotion Law

// No feature branch MR directly to main
forbid (
    principal is Bluefly::Agent,
    action == Bluefly::Action::"OpenMR",
    resource is Bluefly::MergeRequest
) when { context.source_branch_kind == "work" && context.target_branch == "main" };

// Release promotion to main requires Thomas
permit (
    principal == Bluefly::Human::"thomas",
    action == Bluefly::Action::"PromoteToMain",
    resource is Bluefly::Repository
);

---

6. Ten High-Value Mutation Gate Boundaries

Cedar policy enforcement is targeted at ten critical mutation boundaries:

1. Work Claiming (ClaimBead): Ensures worker possesses required role and active city context.
2. Source Mutation (ModifySource, CommitSource): Prevents unauthorized roles from mutating source trees.
3. MR Creation & Branch Target (OpenMR): Enforces target branch rule (release/v0.1.x, never main).
4. MR Merge (MergeToRelease): Requires green CI, zero unresolved discussions, conflict-free state.
5. Runtime Mutation (MutateRuntime): Restricts direct runtime mutation to MAYOR.
6. Deployment (DeployRuntime): Validates deployment package origin and release tags.
7. Secret Resolution (ResolveSecret): Gates 1Password secret injection to authorized CI/agent principals.
8. Policy Mutation (ModifyPolicy): Restricts Cedar schema and policy changes to authorized governance workflows.
9. Destructive Filesystem Operations (DeleteWorkspace): Guards against recursive workstation cleanups (trash, never rm).
10. Bead Close & Completion Certification (CloseBead): Validates complete verification evidence before closing work.

---

7. Deterministic Bead Close & Completion Gates

Bead transitions are gated by policy. An agent cannot close a Bead by merely reporting completion in chat. Action::"CloseBead" requires verified request context:

permit (
    principal is Bluefly::Agent,
    action == Bluefly::Action::"CloseBead",
    resource is Bluefly::Bead
) when {
    context.source_pushed == true &&
    context.mr_merged == true &&
    context.release_contains_change == true &&
    context.required_verifier_passed == true
};

For high-risk capability changes, context.witness_passed == true is required.

---

8. Repository Structure & CI Schema Governance

The blueflyio/cedar-policies repository owns all policy definitions:

cedar_policies/
├── schema/
│   └── bluefly-factory.cedarschema
├── policies/
│   ├── authority/
│   ├── agents/
│   ├── git/
│   ├── runtime/
│   ├── secrets/
│   ├── beads/
│   └── release/
├── tests/
│   ├── allow/
│   └── deny/
├── docs/
└── README.md

Shared CI Verification Suite (gitlab_components)

Every policy change must pass the automated policy test suite before merge: - CEDAR_PARSE=PASS: Syntax check on all .cedar files. - CEDAR_SCHEMA_VALIDATION=PASS: Schema validation against bluefly-factory.cedarschema. - POLICY_TESTS=PASS: Positive scenario evaluation tests. - NEGATIVE_TESTS=PASS: Explicit negative boundary tests. - DEFAULT_DENY_TEST=PASS: Verifies default deny for unmapped actions. - FORBID_OVERRIDE_TEST=PASS: Confirms forbid rules override permit rules.

---

9. Rule Projection Architecture

cedar_policies is the single authority for operational rules.

   cedar_policies (Canonical Cedar Rules & Schema)
                 |
                 +-------------------+-------------------+
                 |                                       |
                 v                                       v
      Cedar Evaluator (PDP Engine)            Generated Role Summaries
     (Runtime Authorization Gate)           (Projections into OpenCode /
                                             Gas City Agent Prompts)

Prompt files receive auto-generated projections derived from Cedar policies. If an agent prompt drifts from the underlying Cedar policy, Cedar policy overrides and denies unauthorized requests at runtime.

---

10. Control Plane Defect Governance

Issues such as native_store_unavailable or project_id host/port mismatches are control-plane defects to be resolved at the Gas City/Beads binding layer (bd dolt set against HQ). Agents must never normalize bypassing gc or creating ad-hoc local stores to work around control-plane binding errors.