feat(sealed): sealed journey + docs (§11 tail M5)

- tests/sealed.rs: a group declares a sealed [[routes]] template; a descendant
  that suppresses it still serves the path, apply warns "sealed — no effect",
  routes ls --group shows sealed=true, and sealing an [app] route is rejected.
- docs: §4.5 trust-model callout + CLAUDE.md move `sealed` from Deferred to
  implemented — group templates are advisory-by-default *unless* sealed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/picloud-cli/tests/cli.rs

@@ -41,6 +41,7 @@ mod pull;
 mod roles;
 mod routes;
 mod scripts;
+mod sealed;
 mod secrets;
 mod staleness;
 mod suppress;

crates/picloud-cli/tests/sealed.rs

@@ -0,0 +1,175 @@
+//! §11 tail — `sealed` (non-suppressible) group templates, end to end via
+//! `pic`. A group declares a **sealed** `[[routes]]` template; a descendant app
+//! that applies a `[suppress] routes=[...]` for it STILL serves the inherited
+//! path (the rebuild keeps a sealed row), the apply emits an ineffective-suppress
+//! warning, and `pic routes ls --group` shows `sealed = true`. Sealing an
+//! `[app]` route is rejected — sealing marks a *group* template, and an app
+//! route is never inherited.
+//!
+//! The repo-layer proof (a sealed trigger + route survive suppression while an
+//! unsealed sibling is declined) lives in
+//! `manager-core/tests/sealed_templates.rs`; this journey exercises the
+//! authoring + the orchestrator dispatch path the operator uses.
+
+use std::fs;
+
+use tempfile::TempDir;
+
+use crate::common;
+use crate::common::cleanup::{AppGuard, GroupGuard, ScriptGuard};
+
+fn manifest_dir() -> TempDir {
+    let dir = TempDir::new().expect("tempdir");
+    fs::create_dir_all(dir.path().join("scripts")).expect("scripts dir");
+    dir
+}
+
+fn group_script_id(env: &common::TestEnv, group: &str, name: &str) -> String {
+    let ls = common::pic_as(env)
+        .args(["scripts", "ls", "--group", group])
+        .output()
+        .expect("scripts ls");
+    let table = String::from_utf8(ls.stdout).unwrap();
+    table
+        .lines()
+        .map(common::cells)
+        .find(|c| c.get(2) == Some(&name))
+        .and_then(|c| c.first().map(|s| (*s).to_string()))
+        .unwrap_or_else(|| panic!("group script `{name}` not found:\n{table}"))
+}
+
+fn route_matches(env: &common::TestEnv, app: &str, url: &str) -> bool {
+    let out = common::pic_as(env)
+        .args(["routes", "match", "--app", app, url])
+        .output()
+        .expect("routes match");
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    stdout.contains("matched") && stdout.contains("true")
+}
+
+#[ignore = "needs DATABASE_URL pointing at a running Postgres"]
+#[test]
+fn sealed_route_template_ignores_suppression() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("seal-grp");
+
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+
+    // Group handler + a SEALED route template binding it.
+    let dir = manifest_dir();
+    fs::write(
+        dir.path().join("scripts/ghealth.rhai"),
+        r#"log::info("group health"); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/ghealth.rhai"))
+        .args(["--group", &group, "--name", "ghealth"])
+        .assert()
+        .success();
+    let _gs = ScriptGuard::new(
+        &env.url,
+        &env.token,
+        &group_script_id(&env, &group, "ghealth"),
+    );
+
+    let gmanifest = format!(
+        "[group]\nslug = \"{group}\"\nname = \"SealG\"\n\n\
+         [[routes]]\nscript = \"ghealth\"\npath = \"/ghealth\"\npath_kind = \"exact\"\n\
+         host_kind = \"any\"\nsealed = true\n"
+    );
+    let gpath = dir.path().join("group.toml");
+    fs::write(&gpath, &gmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&gpath)
+        .assert()
+        .success();
+
+    // `pic routes ls --group` shows the sealed column true.
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["routes", "ls", "--group", &group])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    let sealed_row = ls
+        .lines()
+        .map(common::cells)
+        .find(|c| c.contains(&"/ghealth"))
+        .unwrap_or_else(|| panic!("no /ghealth row in routes ls --group:\n{ls}"));
+    assert!(
+        sealed_row.contains(&"true"),
+        "the sealed column must read true for /ghealth:\n{ls}"
+    );
+
+    // A descendant app inherits it.
+    let blog = common::unique_slug("seal-blog");
+    let _ba = AppGuard::new(&env.url, &env.token, &blog);
+    common::pic_as(&env)
+        .args(["apps", "create", &blog, "--group", &group])
+        .assert()
+        .success();
+    assert!(route_matches(&env, &blog, "http://localhost/ghealth"));
+
+    // blog tries to suppress the inherited route — but it is SEALED, so the
+    // opt-out is ignored: the route keeps serving, and the apply warns.
+    let amanifest = format!(
+        "[app]\nslug = \"{blog}\"\nname = \"Blog\"\n\n\
+         [suppress]\nroutes = [\"/ghealth\"]\n"
+    );
+    let apath = dir.path().join("app.toml");
+    fs::write(&apath, &amanifest).unwrap();
+    let out = common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&apath)
+        .output()
+        .expect("apply blog");
+    assert!(out.status.success(), "blog apply failed: {out:?}");
+    let combined = format!(
+        "{}{}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+    assert!(
+        combined.to_lowercase().contains("sealed") && combined.to_lowercase().contains("no effect"),
+        "suppressing a sealed template must warn it has no effect:\n{combined}"
+    );
+    assert!(
+        route_matches(&env, &blog, "http://localhost/ghealth"),
+        "a sealed template is non-suppressible — the route must still serve"
+    );
+
+    // Sealing an APP route is rejected — sealing marks a group template, and an
+    // app route is never inherited.
+    let bad = format!(
+        "[app]\nslug = \"{blog}\"\nname = \"Blog\"\n\n\
+         [[routes]]\nscript = \"ghealth\"\npath = \"/own\"\npath_kind = \"exact\"\n\
+         host_kind = \"any\"\nsealed = true\n"
+    );
+    fs::write(&apath, &bad).unwrap();
+    let out = common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&apath)
+        .output()
+        .expect("apply bad");
+    assert!(
+        !out.status.success(),
+        "an [app] route cannot be sealed — apply must fail"
+    );
+    let err = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        err.to_lowercase().contains("sealed"),
+        "the rejection must mention sealing:\n{err}"
+    );
+}

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

@@ -438,16 +438,26 @@ Two distinct constraints:
 > A dangling suppress (matching no inherited template) is an apply-time **warning**, not an error;
 > read-only `pic suppress ls --app`.
 >
-> **Trust-model consequence — group templates are now advisory-by-default.** Before opt-out, a group
+> **Trust-model consequence — group templates are advisory-by-default *unless* `sealed`.** Before opt-out,
-> template was *guaranteed* to run on every descendant; with suppression the guarantee weakens to "runs
+> a group template was *guaranteed* to run on every descendant; with suppression the guarantee weakens to
-> unless the descendant declines." This is fine for convenience templates (a shared webhook, a default
+> "runs unless the descendant declines." This is fine for convenience templates (a shared webhook, a
-> route) but is a **footgun for compliance** templates — an audit-logging or security trigger a
+> default route) but was a **footgun for compliance** templates — an audit-logging or security trigger a
-> multi-tenant operator deploys at a group can be silently opted out of by a tenant app. There is
+> multi-tenant operator deploys at a group could be silently opted out of by a tenant app.
-> currently **no non-suppressible flag**; an operator who needs an unconditional hook must not rely on a
+>
-> group template for it (deploy it per-app, or gate at the platform layer). **Deferred:** a `sealed` /
+> **Resolved — `sealed` (mandatory) templates (✅).** A `[group]` marks a route or event-trigger template
-> `mandatory` marker on a group template that the trigger anti-join + route filter skip (making it
+> `sealed = true`; the two suppression filters skip a sealed row, so a descendant's `[suppress]` is
-> non-declinable) — cheap to add since both filters are centralized; and group-level suppression
+> **ignored** and it fires/serves on every descendant. Backing: a `sealed BOOLEAN` column on `triggers` +
-> (decline an ancestor's template for a whole subtree).
+> `routes` (`0059_sealed_templates.sql`); the trigger anti-join gains `AND t.sealed = FALSE` (a sealed row
+> is never excluded → fires through the opt-out), and `compile_effective_routes` gates its suppression
+> `continue` on `!er.route.sealed`. `sealed` is authored **per-template** and is **group-only** —
+> `validate_bundle_for` rejects it on an app owner (an app route/trigger is never inherited, so sealing it
+> is meaningless). It only *strengthens* the guarantee (a sealed template can't be declined; it never
+> grants new reach — the chain walk stays the isolation boundary). It joins the route Update comparison +
+> the trigger identity, so toggling it re-applies (a trigger toggle needs `--prune` to drop the stale
+> row, like any definitional change). A suppression that matches only sealed templates is an apply-time
+> **warning** ("… is sealed — the suppression has no effect"); `pic triggers/routes ls --group` show a
+> `sealed` column. Pinned by `manager-core/tests/sealed_templates.rs` + the `sealed` journey.
+> **Deferred:** group-level suppression (decline an ancestor's template for a whole subtree).
 
 ### 4.6 Secrets & `pull`