feat(suppress): suppression journey + docs (§11 tail S5)

- Journey tests/suppress.rs: a group declares a `[[routes]]` template; a
  descendant app applies `[suppress] routes=["/ghello"]` → stops serving it
  (via `routes match`), a sibling still serves it, `pic suppress ls --app`
  shows it, re-apply is a NoOp; pruning the block re-inherits. The
  trigger-side filter + isolation are pinned at the repo layer by
  template_suppression.rs.
- Docs: design §4.5 (per-app opt-out closing the deferred gap for both
  templates — coarse-by-reference, inheritance-only, the two consumption
  points; group-level suppress still deferred), CLAUDE.md current-focus.

Full journey suite 121/121; workspace tests 34 suites/0 failures.

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

crates/picloud-cli/tests/cli.rs

@@ -43,6 +43,7 @@ mod routes;
 mod scripts;
 mod secrets;
 mod staleness;
+mod suppress;
 mod tree;
 mod triggers;
 mod vars;

crates/picloud-cli/tests/suppress.rs

@@ -0,0 +1,177 @@
+//! §11 tail — per-app opt-out of inherited group templates, end to end via
+//! `pic`. A group declares a `[[routes]]` template; a descendant app applies a
+//! `[suppress] routes=[...]` block → the inherited path stops serving (verified
+//! via `routes match` against the live RouteTable), `pic suppress ls --app`
+//! shows it, re-apply is a NoOp; a sibling app still serves it; pruning the
+//! `[suppress]` block re-inherits the route.
+//!
+//! The trigger-side filter + the isolation (sibling unaffected, own-trigger
+//! still fires) are pinned deterministically at the repo layer by
+//! `manager-core/tests/template_suppression.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 app_suppresses_inherited_route_template() {
+    let Some(fx) = common::fixture_or_skip() else {
+        return;
+    };
+    let env = common::admin_env(fx);
+    let group = common::unique_slug("sup-grp");
+
+    let _g = GroupGuard::new(&env.url, &env.token, &group);
+    common::pic_as(&env)
+        .args(["groups", "create", &group])
+        .assert()
+        .success();
+
+    // Group handler + a route template binding it.
+    let dir = manifest_dir();
+    fs::write(
+        dir.path().join("scripts/ghello.rhai"),
+        r#"log::info("group route"); "ok""#,
+    )
+    .unwrap();
+    common::pic_as(&env)
+        .args(["scripts", "deploy"])
+        .arg(dir.path().join("scripts/ghello.rhai"))
+        .args(["--group", &group, "--name", "ghello"])
+        .assert()
+        .success();
+    let _gs = ScriptGuard::new(
+        &env.url,
+        &env.token,
+        &group_script_id(&env, &group, "ghello"),
+    );
+
+    let gmanifest = format!(
+        "[group]\nslug = \"{group}\"\nname = \"SupG\"\n\n\
+         [[routes]]\nscript = \"ghello\"\npath = \"/ghello\"\npath_kind = \"exact\"\n\
+         host_kind = \"any\"\n"
+    );
+    let gpath = dir.path().join("group.toml");
+    fs::write(&gpath, &gmanifest).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&gpath)
+        .assert()
+        .success();
+
+    // Two descendant apps: `blog` will suppress, `shop` will not.
+    let blog = common::unique_slug("sup-blog");
+    let shop = common::unique_slug("sup-shop");
+    let _ba = AppGuard::new(&env.url, &env.token, &blog);
+    let _sa = AppGuard::new(&env.url, &env.token, &shop);
+    for app in [&blog, &shop] {
+        common::pic_as(&env)
+            .args(["apps", "create", app, "--group", &group])
+            .assert()
+            .success();
+    }
+    // Both inherit the template initially.
+    assert!(route_matches(&env, &blog, "http://localhost/ghello"));
+    assert!(route_matches(&env, &shop, "http://localhost/ghello"));
+
+    // blog applies a [suppress] block declining /ghello.
+    let amanifest = format!(
+        "[app]\nslug = \"{blog}\"\nname = \"Blog\"\n\n\
+         [suppress]\nroutes = [\"/ghello\"]\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:?}");
+
+    // blog no longer serves /ghello; shop still does (per-app boundary).
+    assert!(
+        !route_matches(&env, &blog, "http://localhost/ghello"),
+        "the suppressing app must stop serving the inherited route"
+    );
+    assert!(
+        route_matches(&env, &shop, "http://localhost/ghello"),
+        "a sibling app that did not suppress must still serve it"
+    );
+
+    // `pic suppress ls --app` shows the marker.
+    let ls = String::from_utf8(
+        common::pic_as(&env)
+            .args(["suppress", "ls", "--app", &blog])
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        ls.contains("route") && ls.contains("/ghello"),
+        "suppress ls should list the route suppression:\n{ls}"
+    );
+
+    // Re-apply is a NoOp (marker already present).
+    let report = String::from_utf8(
+        common::pic_as(&env)
+            .args(["apply", "--file"])
+            .arg(&apath)
+            .output()
+            .unwrap()
+            .stdout,
+    )
+    .unwrap();
+    assert!(
+        report.contains("suppressions") && report.contains("+0"),
+        "re-apply should not create a second suppression:\n{report}"
+    );
+
+    // Drop the [suppress] block + prune → blog re-inherits the route.
+    let bare = format!("[app]\nslug = \"{blog}\"\nname = \"Blog\"\n");
+    fs::write(&apath, &bare).unwrap();
+    common::pic_as(&env)
+        .args(["apply", "--file"])
+        .arg(&apath)
+        .args(["--prune", "--yes"])
+        .assert()
+        .success();
+    assert!(
+        route_matches(&env, &blog, "http://localhost/ghello"),
+        "pruning the suppression must re-inherit the route"
+    );
+}

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

@@ -417,9 +417,27 @@ Two distinct constraints:
 > Authoring is `[[routes]]` on a `[group]`; read-only `pic routes ls --group`. **Disabled semantic
 > (§4.3):** the shadow check runs *after* the `enabled` filter, so a **disabled** own-route does not
 > claim its binding — an enabled ancestor template at the same path then falls through and serves
-> ("disabled = absent"). The corollary: a descendant can't 404 an inherited route by disabling a
-> same-path own route. **Deferred:** per-app route opt-out (the true way to decline an inherited
-> route), and multi-node route-snapshot propagation (cluster mode).
+> ("disabled = absent"). To actually 404 an inherited route, an app SUPPRESSES its path (below).
+> **Deferred:** multi-node route-snapshot propagation (cluster mode).
+>
+> **Shipped — per-app opt-out of inherited templates (suppression).** A descendant could shadow a
+> template but not decline one; for triggers there was no decline path at all (an app's own identical
+> trigger double-fires). An app now declares `[suppress]` — `triggers = [...]` (handler SCRIPT names)
+> and `routes = [...]` (PATHS) — to opt out of inherited group templates. **Coarse by reference,** not
+> a full definition (template row-ids churn on re-apply; a reference is stable, so re-apply is a NoOp
+> and a reference may decline several templates bound to the same script/path). Marker table
+> `0058_template_suppressions.sql` — app-only (`app_id NOT NULL`, ON DELETE CASCADE; a group just
+> wouldn't declare the template), a `target_kind` discriminator (`trigger`|`route`), reconciled with the
+> extension-point marker pattern (idempotent create, prunable delete → the template re-inherits).
+> **Consumed at the two existing resolution points:** the trigger dispatch queries gain a correlated
+> `NOT EXISTS` anti-join (excluding a group-owned trigger whose handler the app suppresses, gated to
+> `t.group_id IS NOT NULL`), and `compile_effective_routes` drops an inherited (`depth > 0`) route at a
+> suppressed path (loaded once per rebuild via `RouteRepository::list_route_suppressions`). **Suppression
+> is inheritance-only** — the `group_id IS NOT NULL` / `depth > 0` gates mean an app can only decline
+> what it inherits, never its own resource nor a sibling's (pinned by `tests/template_suppression.rs`).
+> A dangling suppress (matching no inherited template) is an apply-time **warning**, not an error;
+> read-only `pic suppress ls --app`. **Deferred:** group-level suppression (decline an ancestor's
+> template for a whole subtree).
 
 ### 4.6 Secrets & `pull`