feat(hierarchies): per-env approval-policy gating (M5)

A project's root manifest can mark environments confirm-required; applying to
one needs an explicit `pic apply --dir --env <e> --approve <e>` (a blanket
`--yes` does NOT cover it), the act is admin-gated and audited, and the policy
folds into the bound-plan token. The last unbuilt piece of the project-tool
track (§4.2/§6).

- manifest: `[project]` block → `ManifestProject { environments[{name,confirm}] }`,
  valid only on the tree's ROOT manifest (rejected elsewhere by build_tree).
- discover: build_tree emits `project` into the bundle from the root manifest.
- apply_service: `TreeBundle.project` + `ProjectPolicy`; policy folds into the
  state_token (a policy edit between plan and apply trips StateMoved); plan
  surfaces `approvals_required`; new `ApplyError::ApprovalRequired` → 409.
- apply_api: `enforce_env_approval` (after authz_tree) — refuses a gated env
  not in `approved_envs`, and on approval requires admin (AppAdmin/GroupAdmin)
  on every declared node + audits. The server re-derives the policy from the
  bundle (CLI check is convenience; server is authoritative).
- CLI: `--approve <env>` (repeatable); `resolve_approvals` refuses a gated env
  non-interactively, prompts on a TTY (retype the env name); plan renders gated
  envs. Single-node `apply --file --env <e>` REFUSES a confirm-required env
  (can't carry the admin-gated approval) and directs to `--dir` — closing the
  bypass found in review rather than silently skipping the gate.
- approval journey + manifest/ProjectPolicy unit tests. No migration (policy
  lives in the manifest, like takeover/blast-radius).
- doc §11 Phase 5 + §12: approval gating shipped; gate is a `--dir` feature.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

crates/manager-core/src/apply_api.rs

@@ -206,6 +206,11 @@ struct TreeApplyRequest {
     /// placeholder when expanding route templates. The CLI passes `--env`.
     #[serde(default)]
     env: Option<String>,
+    /// Environments the actor explicitly approved this apply for (§4.2, M5).
+    /// A confirm-required env (per the bundle's `[project]` policy) is refused
+    /// unless it appears here; `--yes` alone does NOT add it.
+    #[serde(default)]
+    approved_envs: Vec<String>,
 }
 
 async fn tree_plan_handler(
@@ -233,6 +238,14 @@ async fn tree_apply_handler(
         req.allow_takeover,
     )
     .await?;
+    enforce_env_approval(
+        &svc,
+        &principal,
+        &req.bundle,
+        req.env.as_deref(),
+        &req.approved_envs,
+    )
+    .await?;
     let report = svc
         .apply_tree(
             &req.bundle,
@@ -438,6 +451,64 @@ async fn authz_tree(
     Ok(())
 }
 
+/// Per-env approval gate (§4.2, §6, M5). If the apply selects a confirm-required
+/// environment (per the bundle's `[project]` policy, re-derived here — the CLI's
+/// enforcement is convenience, this is authoritative), it must be explicitly
+/// approved via `approved_envs` (`pic apply --approve <env>`); a blanket `--yes`
+/// does NOT satisfy it. An approved gated apply additionally requires ADMIN
+/// authority on every declared node — the "override a gate" capability (§4.2),
+/// a deliberate step up from the editor-level write caps an ordinary apply
+/// needs — and is audited.
+async fn enforce_env_approval(
+    svc: &ApplyService,
+    principal: &Principal,
+    bundle: &TreeBundle,
+    env: Option<&str>,
+    approved_envs: &[String],
+) -> Result<(), ApplyError> {
+    let (Some(policy), Some(env)) = (&bundle.project, env) else {
+        return Ok(());
+    };
+    if !policy.confirm_required(env) {
+        return Ok(());
+    }
+    if !approved_envs.iter().any(|e| e == env) {
+        return Err(ApplyError::ApprovalRequired(env.to_string()));
+    }
+    // Approved: require admin authority on every declared node.
+    for node in &bundle.nodes {
+        match node.kind {
+            NodeKind::App => {
+                let app_id = resolve_app_id(svc.apps.as_ref(), &node.slug).await?;
+                require(svc.authz.as_ref(), principal, Capability::AppAdmin(app_id))
+                    .await
+                    .map_err(map_authz)?;
+            }
+            NodeKind::Group => {
+                // A to-create group has no id yet; its creation already required
+                // InstanceCreateGroup / GroupAdmin(parent) in `authz_tree`.
+                if let Some(g) = svc
+                    .groups
+                    .get_by_slug(&node.slug)
+                    .await
+                    .map_err(|e| ApplyError::Backend(e.to_string()))?
+                {
+                    require(svc.authz.as_ref(), principal, Capability::GroupAdmin(g.id))
+                        .await
+                        .map_err(map_authz)?;
+                }
+            }
+        }
+    }
+    tracing::info!(
+        user_id = ?principal.user_id,
+        env = %env,
+        nodes = bundle.nodes.len(),
+        "apply: approved gated-environment apply (audit)"
+    );
+    Ok(())
+}
+
 /// App-node write caps: per resource kind the bundle touches, widened to all
 /// kinds when `prune` (which deletes empty-section resources + cascades). Read
 /// is always needed. Shared by the single-app and tree apply paths.
@@ -679,7 +750,7 @@ impl IntoResponse for ApplyError {
                 json!({ "error": self.to_string() }),
             ),
             Self::StateMoved => (StatusCode::CONFLICT, json!({ "error": self.to_string() })),
-            Self::OwnershipConflict(_) => {
+            Self::OwnershipConflict(_) | Self::ApprovalRequired(_) => {
                 (StatusCode::CONFLICT, json!({ "error": self.to_string() }))
             }
             Self::Forbidden => (StatusCode::FORBIDDEN, json!({ "error": self.to_string() })),

crates/manager-core/src/apply_service.rs

@@ -453,6 +453,46 @@ pub struct TreeNode {
 pub struct TreeBundle {
     #[serde(default)]
     pub nodes: Vec<TreeNode>,
+    /// Project-level policy from the repo's root manifest `[project]` block
+    /// (§4.2/§6, M5). The server re-derives env approval policy from here —
+    /// the CLI's enforcement is convenience, this is authoritative.
+    #[serde(default)]
+    pub project: Option<ProjectPolicy>,
+}
+
+/// Project-level policy (the root manifest's `[project]` block, M5).
+#[derive(Debug, Clone, Default, Deserialize)]
+pub struct ProjectPolicy {
+    #[serde(default)]
+    pub environments: Vec<EnvPolicy>,
+}
+
+/// One environment's apply policy. `confirm = true` makes applying to this env a
+/// gated, default-off step: a per-env `--approve <name>` is required (a blanket
+/// `--yes` does NOT cover it) and the act is admin-gated + audited (§4.2).
+#[derive(Debug, Clone, Deserialize)]
+pub struct EnvPolicy {
+    pub name: String,
+    #[serde(default)]
+    pub confirm: bool,
+}
+
+impl ProjectPolicy {
+    /// Does environment `env` require explicit approval to apply?
+    #[must_use]
+    pub fn confirm_required(&self, env: &str) -> bool {
+        self.environments.iter().any(|e| e.name == env && e.confirm)
+    }
+
+    /// Names of every confirm-required environment (for `plan` to surface).
+    #[must_use]
+    pub fn gated_envs(&self) -> Vec<String> {
+        self.environments
+            .iter()
+            .filter(|e| e.confirm)
+            .map(|e| e.name.clone())
+            .collect()
+    }
 }
 
 /// One node's diff within a tree plan.
@@ -485,6 +525,11 @@ pub struct TreePlanResult {
     /// expansions. Lets CI gauge the fan-out before applying.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub template_blast_radius: Vec<TemplateBlastRadius>,
+    /// Environments the project marks confirm-required (§4.2, M5): applying to
+    /// one needs an explicit `pic apply --approve <env>`. Surfaced so CI sees
+    /// the gate at `plan` time, before an `apply` refuses.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub approvals_required: Vec<String>,
 }
 
 /// One group's route-template fan-out within the current apply.
@@ -552,6 +597,11 @@ pub enum ApplyError {
          re-run with `--takeover` to claim them (group-admin required): {0}"
     )]
     OwnershipConflict(String),
+    #[error(
+        "environment `{0}` requires explicit approval to apply; \
+         re-run with `--approve {0}` (a blanket `--yes` does not cover it)"
+    )]
+    ApprovalRequired(String),
     #[error("authorization repo error: {0}")]
     AuthzRepo(String),
     #[error("backend: {0}")]
@@ -1268,12 +1318,18 @@ impl ApplyService {
                 plan: compute_diff(&CurrentState::default(), &c.node.bundle),
             });
         }
+        let approvals_required = bundle
+            .project
+            .as_ref()
+            .map(ProjectPolicy::gated_envs)
+            .unwrap_or_default();
         Ok(TreePlanResult {
             nodes,
             state_token: pt.token,
             conflicts: pt.conflicts,
             structural_prunes: pt.prune_candidates.into_iter().map(|(_, s)| s).collect(),
             template_blast_radius: pt.template_blast_radius,
+            approvals_required,
         })
     }
 
@@ -2010,6 +2066,19 @@ impl ApplyService {
             });
         }
 
+        // Fold the env approval policy (desired state) into the token, so a
+        // policy edit between plan and apply trips StateMoved (M5). Sorted for
+        // order-independence.
+        if let Some(policy) = &bundle.project {
+            let mut envs: Vec<String> = policy
+                .environments
+                .iter()
+                .map(|e| format!("{}={}", e.name, e.confirm))
+                .collect();
+            envs.sort_unstable();
+            token_parts.push(format!("proj|{}", envs.join(",")));
+        }
+
         // Fold in every in-scope group's structure version, so a reparent or a
         // new app under the subtree between plan and apply trips StateMoved.
         for gid in &versioned_groups {
@@ -5850,4 +5919,24 @@ mod tests {
             "queue identity is queue_name-only: {p:?}"
         );
     }
+
+    #[test]
+    fn project_policy_gates_only_confirm_required_envs() {
+        let policy = ProjectPolicy {
+            environments: vec![
+                EnvPolicy {
+                    name: "production".into(),
+                    confirm: true,
+                },
+                EnvPolicy {
+                    name: "staging".into(),
+                    confirm: false,
+                },
+            ],
+        };
+        assert!(policy.confirm_required("production"));
+        assert!(!policy.confirm_required("staging"));
+        assert!(!policy.confirm_required("unknown"));
+        assert_eq!(policy.gated_envs(), vec!["production".to_string()]);
+    }
 }

crates/picloud-cli/src/client.rs

@@ -1265,6 +1265,7 @@ impl Client {
     /// transaction (Phase 5). `project_key`/`allow_takeover` drive ownership
     /// (§7, M3): the apply claims unclaimed declared groups for this project and
     /// refuses (or, with `allow_takeover`, seizes) ones another project owns.
+    #[allow(clippy::too_many_arguments)]
     pub async fn apply_tree(
         &self,
         bundle: &serde_json::Value,
@@ -1273,6 +1274,7 @@ impl Client {
         project_key: Option<&str>,
         allow_takeover: bool,
         env: Option<&str>,
+        approved_envs: &[String],
     ) -> Result<ApplyReportDto> {
         let body = serde_json::json!({
             "bundle": bundle,
@@ -1281,6 +1283,7 @@ impl Client {
             "project_key": project_key,
             "allow_takeover": allow_takeover,
             "env": env,
+            "approved_envs": approved_envs,
         });
         let resp = self
             .request(Method::POST, "/api/v1/admin/tree/apply")
@@ -1392,6 +1395,9 @@ pub struct TreePlanDto {
     /// Route-template fan-out per declaring group (§4.5, M4a).
     #[serde(default)]
     pub template_blast_radius: Vec<TemplateBlastRadiusDto>,
+    /// Environments the project marks confirm-required (§4.2, M5).
+    #[serde(default)]
+    pub approvals_required: Vec<String>,
 }
 
 /// A single ownership conflict (`pic plan --dir`).

crates/picloud-cli/src/cmds/apply.rs

@@ -26,6 +26,26 @@ pub async fn run(
     let client = Client::from_creds(&creds)?;
 
     let manifest = Manifest::load_with_env(manifest_path, env)?;
+
+    // Env approval gating (§4.2, M5) is a project-tree (`--dir`) feature: the
+    // admin-gated, audited per-env approval is enforced server-side only on the
+    // tree apply path. Single-node `apply --file` cannot provide that guarantee,
+    // so rather than silently bypass a confirm-required env, refuse and direct
+    // the user to `--dir` (which carries the policy + `--approve` to the server).
+    if let (Some(env), Some(project)) = (env, &manifest.project) {
+        if project
+            .environments
+            .iter()
+            .any(|e| e.name == env && e.confirm)
+        {
+            anyhow::bail!(
+                "environment `{env}` is confirm-required by this project's [project] policy; \
+                 single-node `pic apply --file` cannot provide the admin-gated, audited approval. \
+                 Use `pic apply --dir <root> --env {env} --approve {env}` instead."
+            );
+        }
+    }
+
     let base_dir = manifest_path.parent().unwrap_or_else(|| Path::new("."));
     let bundle = build_bundle(&manifest, base_dir)?;
     let kind = if manifest.is_group() {
@@ -113,6 +133,7 @@ pub async fn run(
 
 /// `pic apply --dir <root>` (Phase 5): reconcile a whole project tree — every
 /// `picloud.toml` under `root` — in ONE atomic server transaction.
+#[allow(clippy::too_many_arguments)]
 pub async fn run_tree(
     dir: &Path,
     prune: bool,
@@ -120,16 +141,24 @@ pub async fn run_tree(
     force: bool,
     takeover: bool,
     env: Option<&str>,
+    approve: &[String],
     mode: OutputMode,
 ) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let (bundle, node_count) = crate::discover::build_tree(dir, env)?;
+    let (bundle, node_count, envs) = crate::discover::build_tree(dir, env)?;
 
     if prune && !yes {
         confirm_prune(&format!("{node_count} node(s) under {}", dir.display()))?;
     }
 
+    // Per-env approval gate (§4.2, M5): if the selected env is confirm-required,
+    // it needs an explicit `--approve <env>` (a TTY may confirm interactively;
+    // `--yes` does NOT cover it). The server re-checks this authoritatively — the
+    // local check just fails fast with a clear message. `approved` is the set
+    // sent on the wire.
+    let approved = resolve_approvals(env, &envs, approve)?;
+
     let token_key = crate::cmds::plan::TREE_TOKEN_KEY;
     let expected_token = if force {
         None
@@ -152,6 +181,7 @@ pub async fn run_tree(
             Some(&project_key),
             takeover,
             env,
+            &approved,
         )
         .await?;
     crate::linkstate::clear_plan(dir, token_key);
@@ -254,6 +284,49 @@ pub async fn run_tree(
     Ok(())
 }
 
+/// Resolve the set of environments the actor approves for this apply (§4.2, M5).
+/// If the selected `env` is confirm-required (per the root manifest's
+/// `[project]` policy) it must be approved — via `--approve <env>`, or an
+/// interactive TTY confirmation that requires re-typing the env name. A blanket
+/// `--yes` does NOT satisfy it. Returns the full approved set to send on the
+/// wire (the server re-checks authoritatively). A non-gated env passes through.
+fn resolve_approvals(
+    env: Option<&str>,
+    policy: &[crate::manifest::ManifestEnvironment],
+    approve: &[String],
+) -> Result<Vec<String>> {
+    let mut approved: Vec<String> = approve.to_vec();
+    let Some(env) = env else {
+        return Ok(approved); // no env selected → nothing env-specific to gate
+    };
+    let gated = policy.iter().any(|e| e.name == env && e.confirm);
+    if !gated || approved.iter().any(|e| e == env) {
+        return Ok(approved);
+    }
+    // Gated and not pre-approved: prompt on a TTY, else refuse (CI must pass
+    // --approve explicitly; --yes is deliberately insufficient).
+    if std::io::stdin().is_terminal() {
+        eprint!(
+            "environment `{env}` requires explicit approval to apply. \
+             Type the environment name to approve, or anything else to abort: "
+        );
+        std::io::stderr().flush().ok();
+        let mut answer = String::new();
+        std::io::stdin()
+            .read_line(&mut answer)
+            .context("read approval")?;
+        if answer.trim() == env {
+            approved.push(env.to_string());
+            return Ok(approved);
+        }
+        anyhow::bail!("aborted: environment `{env}` not approved");
+    }
+    anyhow::bail!(
+        "environment `{env}` requires explicit approval: re-run with `--approve {env}` \
+         (a blanket `--yes` does not cover a confirm-required environment)"
+    );
+}
+
 /// `--prune` deletes live scripts/routes/triggers absent from the manifest —
 /// irreversible. Require an explicit go-ahead: an interactive `y`, or `--yes`
 /// for non-interactive/CI use. Refuse a non-interactive prune without `--yes`

crates/picloud-cli/src/cmds/init.rs

@@ -118,6 +118,7 @@ fn scaffold_manifest(slug: &str, name: &str) -> Manifest {
             description: None,
         }),
         group: None,
+        project: None,
         scripts: vec![ManifestScript {
             name: "hello".into(),
             file: "scripts/hello.rhai".into(),

crates/picloud-cli/src/cmds/plan.rs

@@ -49,7 +49,7 @@ pub async fn run(manifest_path: &Path, env: Option<&str>, mode: OutputMode) -> R
 pub async fn run_tree(dir: &Path, env: Option<&str>, mode: OutputMode) -> Result<()> {
     let creds = config::resolve()?;
     let client = Client::from_creds(&creds)?;
-    let (bundle, _count) = crate::discover::build_tree(dir, env)?;
+    let (bundle, _count, _envs) = crate::discover::build_tree(dir, env)?;
     // Mint/read this repo's project key so the server can report ownership
     // (§7, M3). Best-effort: a read-only dir still plans (ownership unreported).
     let project_key = crate::linkstate::ensure_project_key(dir).ok();
@@ -107,11 +107,17 @@ fn render_tree(plan: &TreePlanDto, mode: OutputMode) {
             }
         }
         if !plan.template_blast_radius.is_empty() {
-            eprintln!("\nroute-template blast radius (apps IN THIS apply that get expansions):");
+            eprintln!("\nroute-template blast radius (every descendant app in the DB subtree):");
             for b in &plan.template_blast_radius {
                 eprintln!("  - {} → {} app(s)", b.group, b.affected_apps);
             }
         }
+        if !plan.approvals_required.is_empty() {
+            eprintln!("\nenvironments requiring explicit approval (apply with --approve <env>):");
+            for e in &plan.approvals_required {
+                eprintln!("  - {e}");
+            }
+        }
     }
 }
 

crates/picloud-cli/src/cmds/pull.rs

@@ -229,6 +229,7 @@ pub async fn run(app_ident: &str, dir: &Path, force: bool, mode: OutputMode) ->
             description: app.app.description.clone(),
         }),
         group: None,
+        project: None,
         scripts: manifest_scripts,
         routes,
         triggers: manifest_triggers,

crates/picloud-cli/src/discover.rs

@@ -45,10 +45,15 @@ fn walk(dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
     Ok(())
 }
 
-/// Build the wire tree bundle (`{ nodes: [{kind, slug, bundle}] }`) from every
-/// manifest under `root`. Returns the JSON plus the node count. Rejects a tree
-/// that names the same (kind, slug) twice.
-pub fn build_tree(root: &Path, env: Option<&str>) -> Result<(Value, usize)> {
+/// Build the wire tree bundle (`{ nodes: [{kind, slug, bundle}], project }`)
+/// from every manifest under `root`. Returns the JSON, the node count, and the
+/// root manifest's `[project]` environment policy (M5, empty if none). Rejects a
+/// tree that names the same (kind, slug) twice, or declares `[project]` anywhere
+/// but the root manifest.
+pub fn build_tree(
+    root: &Path,
+    env: Option<&str>,
+) -> Result<(Value, usize, Vec<crate::manifest::ManifestEnvironment>)> {
     let paths = find_manifests(root)?;
     if paths.is_empty() {
         bail!(
@@ -56,13 +61,27 @@ pub fn build_tree(root: &Path, env: Option<&str>) -> Result<(Value, usize)> {
             root.display()
         );
     }
+    let root_manifest = root.join(MANIFEST_FILE);
     // First pass: load every manifest and index its DIRECTORY → (slug, is_group)
     // so a group node's parent can be inferred from the enclosing directory.
     let mut loaded: Vec<(PathBuf, Manifest)> = Vec::with_capacity(paths.len());
     let mut group_dirs: HashMap<PathBuf, String> = HashMap::new();
+    let mut project: Option<crate::manifest::ManifestProject> = None;
     for path in &paths {
         let manifest = Manifest::load_with_env(path, env)
             .with_context(|| format!("loading {}", path.display()))?;
+        // `[project]` is project-level — valid only on the tree's root manifest.
+        if let Some(p) = &manifest.project {
+            if path == &root_manifest {
+                project = Some(p.clone());
+            } else {
+                bail!(
+                    "{} declares [project], which is only valid on the root manifest ({})",
+                    path.display(),
+                    root_manifest.display()
+                );
+            }
+        }
         let dir = path
             .parent()
             .unwrap_or_else(|| Path::new("."))
@@ -100,7 +119,22 @@ pub fn build_tree(root: &Path, env: Option<&str>) -> Result<(Value, usize)> {
         nodes.push(node);
     }
     let count = nodes.len();
-    Ok((json!({ "nodes": nodes }), count))
+    let envs = project
+        .as_ref()
+        .map(|p| p.environments.clone())
+        .unwrap_or_default();
+    let mut bundle = json!({ "nodes": nodes });
+    if let Some(p) = &project {
+        bundle.as_object_mut().expect("json object").insert(
+            "project".into(),
+            json!({
+                "environments": p.environments.iter()
+                    .map(|e| json!({ "name": e.name, "confirm": e.confirm }))
+                    .collect::<Vec<_>>(),
+            }),
+        );
+    }
+    Ok((bundle, count, envs))
 }
 
 /// The slug of the nearest ancestor directory (above `dir`) that holds a group

crates/picloud-cli/src/main.rs

@@ -228,6 +228,11 @@ struct ApplyArgs {
     /// top of the base manifest before applying.
     #[arg(long)]
     env: Option<String>,
+    /// Tree apply only (`--dir`): explicitly approve applying to a
+    /// confirm-required environment (per the root manifest's `[project]`
+    /// policy, §4.2). Repeatable. A blanket `--yes` does NOT cover it.
+    #[arg(long = "approve", requires = "dir")]
+    approve: Vec<String>,
 }
 
 #[derive(Args)]
@@ -1352,6 +1357,7 @@ async fn main() -> ExitCode {
                     args.force,
                     args.takeover,
                     args.env.as_deref(),
+                    &args.approve,
                     mode,
                 )
                 .await

crates/picloud-cli/src/manifest.rs

@@ -36,6 +36,10 @@ pub struct Manifest {
     pub app: Option<ManifestApp>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub group: Option<ManifestGroup>,
+    /// `[project]` — project-level policy (M5), consumed only by `apply --dir`
+    /// and only on the tree's ROOT manifest (enforced in `build_tree`).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub project: Option<ManifestProject>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub scripts: Vec<ManifestScript>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
@@ -236,6 +240,26 @@ pub struct ManifestGroup {
     pub parent: Option<String>,
 }
 
+/// `[project]` — project-level policy (§4.2/§6, M5). Valid ONLY on the root
+/// manifest of a `pic apply --dir` tree; rejected elsewhere by [`build_tree`].
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManifestProject {
+    /// `[[project.environments]]` — per-env apply policy.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub environments: Vec<ManifestEnvironment>,
+}
+
+/// One `[[project.environments]]` entry. `confirm = true` gates applying to this
+/// env behind an explicit `pic apply --approve <name>` (M5).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ManifestEnvironment {
+    pub name: String,
+    #[serde(default)]
+    pub confirm: bool,
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct ManifestScript {
     pub name: String,
@@ -495,6 +519,7 @@ mod tests {
                 description: Some("demo".into()),
             }),
             group: None,
+            project: None,
             scripts: vec![
                 ManifestScript {
                     name: "create-post".into(),
@@ -659,6 +684,7 @@ mod tests {
                 description: None,
             }),
             group: None,
+            project: None,
             scripts: vec![],
             routes: vec![],
             triggers: ManifestTriggers::default(),
@@ -705,6 +731,23 @@ mod tests {
             .expect_err("both [app] and [group]");
     }
 
+    #[test]
+    fn project_block_parses_environment_policy() {
+        let m = Manifest::parse(
+            "[app]\nslug = \"a\"\nname = \"A\"\n\n\
+             [[project.environments]]\nname = \"production\"\nconfirm = true\n\n\
+             [[project.environments]]\nname = \"staging\"\n",
+        )
+        .expect("manifest with [project] parses");
+        let p = m.project.expect("project present");
+        assert_eq!(p.environments.len(), 2);
+        assert_eq!(p.environments[0].name, "production");
+        assert!(p.environments[0].confirm);
+        // `confirm` defaults to false when omitted.
+        assert_eq!(p.environments[1].name, "staging");
+        assert!(!p.environments[1].confirm);
+    }
+
     #[test]
     fn overlay_vars_override_base_per_key() {
         let mut base = sample();

crates/picloud-cli/tests/approval.rs

@@ -0,0 +1,163 @@
+//! M5 per-env approval gating (§4.2, §6) via `pic apply --dir`:
+//!   * a root manifest `[project]` block marks an environment confirm-required,
+//!   * applying to that env WITHOUT `--approve` is refused (a blanket `--yes`
+//!     does not cover it) — refused non-interactively at the CLI,
+//!   * `--approve <env>` (as an admin) lets it through,
+//!   * a non-gated environment applies with plain `--yes`,
+//!   * approving a gated apply needs ADMIN authority on the node — a non-admin
+//!     editor with `--approve` is refused server-side (403).
+
+use std::fs;
+use std::path::Path;
+
+use tempfile::TempDir;
+
+use crate::common;
+use crate::common::cleanup::{AppGuard, GroupGuard};
+use crate::common::member;
+
+/// A single-app project dir whose root manifest declares a `[project]` policy:
+/// `production` is confirm-required, `staging` is not.
+fn project_dir(app: &str) -> TempDir {
+    let dir = TempDir::new().expect("tempdir");
+    fs::write(
+        dir.path().join("picloud.toml"),
+        format!(
+            "[app]\nslug = \"{app}\"\nname = \"Gated App\"\n\n\
+             [[project.environments]]\nname = \"production\"\nconfirm = true\n\n\
+             [[project.environments]]\nname = \"staging\"\nconfirm = false\n"
+        ),
+    )
+    .unwrap();
+    // `--env <e>` requires the overlay file to exist; empty overlays keep the
+    // base slug (same app across envs — we're testing the gate, not env routing).
+    fs::write(dir.path().join("picloud.production.toml"), "").unwrap();
+    fs::write(dir.path().join("picloud.staging.toml"), "").unwrap();
+    dir
+}
+
+fn apply(env: &common::TestEnv, dir: &Path, extra: &[&str]) -> std::process::Output {
+    let mut cmd = common::pic_as(env);
+    cmd.args(["apply", "--dir"]).arg(dir).args(extra);
+    cmd.output().expect("apply --dir")
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn confirm_required_env_needs_explicit_approval() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("appr-g");
+    let app = common::unique_slug("appr-a");
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+    let _a = AppGuard::new(&env.url, &env.token, &app);
+    common::pic_as(&env)
+        .args(["apps", "create", &app, "--group", &group])
+        .assert()
+        .success();
+
+    let dir = project_dir(&app);
+
+    // --- production is confirm-required: --yes alone is refused. ---
+    let out = apply(&env, dir.path(), &["--env", "production", "--yes"]);
+    assert!(
+        !out.status.success(),
+        "production apply without --approve must be refused"
+    );
+    let err = String::from_utf8_lossy(&out.stderr).to_lowercase();
+    assert!(
+        err.contains("approve"),
+        "refusal should mention --approve:\n{err}"
+    );
+
+    // --- with --approve production, it applies. ---
+    let ok = apply(
+        &env,
+        dir.path(),
+        &["--env", "production", "--approve", "production"],
+    );
+    assert!(
+        ok.status.success(),
+        "approved production apply should succeed: {}",
+        String::from_utf8_lossy(&ok.stderr)
+    );
+
+    // --- staging is NOT gated: plain --yes applies. ---
+    let ok2 = apply(&env, dir.path(), &["--env", "staging", "--yes"]);
+    assert!(
+        ok2.status.success(),
+        "non-gated staging apply should succeed: {}",
+        String::from_utf8_lossy(&ok2.stderr)
+    );
+
+    // --- single-node `apply --file` to a gated env is refused (no silent
+    // bypass): the admin-gated approval is a `--dir` feature. ---
+    let single = common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(dir.path().join("picloud.toml"))
+        .args(["--env", "production", "--yes"])
+        .output()
+        .expect("apply --file");
+    assert!(
+        !single.status.success(),
+        "single-node apply to a confirm-required env must be refused"
+    );
+    let serr = String::from_utf8_lossy(&single.stderr).to_lowercase();
+    assert!(
+        serr.contains("confirm-required") || serr.contains("--dir"),
+        "single-node refusal should point at --dir:\n{serr}"
+    );
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn approving_a_gated_apply_requires_admin() {
+    // §4.2: approving a confirm-required env is admin-gated — a second gate on
+    // top of the editor-level write caps an ordinary apply needs. An editor who
+    // CAN write the app still cannot approve a gated apply.
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("appr2-g");
+    let app = common::unique_slug("appr2-a");
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+    let _a = AppGuard::new(&env.url, &env.token, &app);
+    common::pic_as(&env)
+        .args(["apps", "create", &app, "--group", &group])
+        .assert()
+        .success();
+
+    // A member with `editor` (write) on the app — enough for an ordinary apply,
+    // not enough to approve a gated environment.
+    let m = member::member_user(fx, &common::unique_username("appr"));
+    member::grant_membership(fx, &app, &m.id, "editor");
+    let member_env = common::custom_env(&fx.url, &m.token);
+    common::seed_credentials(&member_env, &m.username);
+
+    let dir = project_dir(&app);
+    let out = apply(
+        &member_env,
+        dir.path(),
+        &["--env", "production", "--approve", "production"],
+    );
+    assert!(
+        !out.status.success(),
+        "a non-admin editor must not be able to approve a gated apply"
+    );
+    let err = String::from_utf8_lossy(&out.stderr).to_lowercase();
+    assert!(
+        err.contains("forbidden") || err.contains("403"),
+        "approval denial should be an authz error:\n{err}"
+    );
+}

crates/picloud-cli/tests/cli.rs

@@ -16,6 +16,7 @@ mod common;
 mod admins;
 mod api_keys;
 mod apply;
+mod approval;
 mod apps;
 mod auth;
 mod config;

docs/design/groups-and-project-tool.md

@@ -1064,9 +1064,18 @@ Resolved items now live inline next to their topic. What genuinely remains:
    > directory tree of `picloud.toml` manifests (each declaring an `[app]` or `[group]` node) applies as
    > ONE server-computed plan in ONE Postgres transaction. **Declarative group create/reparent shipped
    > (M2, 2026-06-26)** — a manifest now owns the tree *shape*, not just node content. **Multi-repo
-   > single-owner / takeover + structural prune shipped (§7, M3, 2026-06-26)** — see §7 below. Still
-   > deferred: **per-env approval-policy gating** (`[project.environments]`); env overlays
-   > (`picloud.<env>.toml`) already exist.
+   > single-owner / takeover + structural prune shipped (§7, M3, 2026-06-26)** — see §7 below.
+   > **Per-env approval-policy gating shipped (`[project.environments]`, M5, 2026-06-28)** — the root
+   > manifest declares which environments are confirm-required; `pic apply --dir --env <e>` to such an
+   > env needs an explicit `--approve <e>` (a blanket `--yes` does NOT cover it), the approval is
+   > admin-gated (the actor needs admin on every declared node, not just write) and audited, and the
+   > policy folds into the bound-plan token. The server re-derives the policy from the bundle — the CLI's
+   > check is convenience, the server is authoritative. Env overlays (`picloud.<env>.toml`) already exist.
+   > Gating is a **`--dir` (project-tree) feature**: single-node `pic apply --file --env <e>` cannot
+   > carry the admin-gated approval, so it **refuses** a confirm-required env and directs the user to
+   > `--dir` (rather than silently bypassing the gate). Like `--takeover`/blast-radius, the policy lives
+   > in the manifest (not persisted server-side), so whoever controls desired state can weaken it — an
+   > accepted trust boundary, not a privilege bug.
    >
    > Shipped surface:
    > - **Engine:** the reconcile engine generalized from app-only to an `ApplyOwner { App | Group }`
@@ -1131,3 +1140,7 @@ to take, not yet taken:
   §11.3. The remaining contract work here is only for script-body inheritance, Phase 4.)*
 - The **full manifest schema** spelling every block (scripts, routes, the 8 trigger kinds, storage
   config, env-scoped vars, secret-refs, domains, `[project.environments]` + confirm policy).
+  > `[project]` (M5, root manifest only) shipped: `[[project.environments]]` entries carry
+  > `name` + `confirm` (default `false`). A `confirm = true` env is gated — `pic apply --dir --env <name>`
+  > requires `--approve <name>` (admin-gated + audited; `--yes` is insufficient). The block is rejected on
+  > any non-root manifest. Remaining unspecified: storage config, domains, the full secret-ref shape.