feat(hooks): ship it experimental — a hook gets no vote on the build

`[hooks]` is marked experimental, and the marking is enforced rather than
written down: `side_effect` now defaults to FALSE, and `side_effect = true` is
REFUSED by the manifest parser.

    error: mcpp.toml: error: [hooks].side_effect = true is not available yet:
    [hooks] is experimental and cannot decide whether a build succeeded. …

So every hook failure — cannot start, non-zero, timed out, failed to stay up —
is a warning, and `mcpp build` keeps the result it earned on its own.

Refused rather than quietly downgraded, because both silent behaviours are
worse than an error. Honouring `true` would ship an experimental feature with a
veto over every build. Ignoring it would leave a project believing its build is
gated on a notifier when nothing is — which is the "accepted and does nothing"
shape this design already rejects for `loop` on a self-closing event and for
`timeout_seconds` on `during_build`. Making an exception for the one key whose
wrong answer is invisible would be exactly backwards.

The key stays in the schema, so a manifest written today does not have to
change when the feature is promoted, and the mechanism under it already
implements both values: the `sideEffect == true` branch in `mcpp.hooks` is
unreachable today ON PURPOSE. Promotion is the deletion of one block in the
parser, not a reconstruction.

Two further limits are documented as permanent rather than provisional, so they
are not read as part of the experiment: a dependency's `[hooks]` is skipped
always (there is one Span construction and there are two invoke call sites, all
in run_build_with_hooks, all fed from the context's own manifest), and only
`mcpp build` runs hooks.

Criteria: the e2e now asserts BOTH halves — the exit code says the hook had no
vote, and the warning says the failure was not swallowed. Checking only the
exit code would pass just as well if hooks had stopped running altogether. The
timeout and give-up cases flipped from "build fails with error:" to "build
succeeds with warning:", and a negative assertion was rewritten as `if grep`
rather than `grep && { }`, whose exit status under `set -e` is an argument this
file should not be having.

Hook context (MCPP_PROFILE, MCPP_TARGET, …) is deferred; the experimental
window is where that interface can still be named deliberately.

Author: speak-agent

.agents/docs/2026-08-30-project-build-hooks-owned-intervals.md

@@ -178,6 +178,37 @@ would interleave into the middle of a compiler diagnostic. Its output is
 therefore discarded by default, and inherited under `--verbose` — no new schema
 key, and the answer to "why is there no music" is one flag away.
 
+## Shipping it experimental
+
+The feature ships with `side_effect` defaulting to **false** and `true`
+*refused* by the manifest parser. A hook therefore cannot change whether a
+build succeeded: every failure is a warning and `mcpp build` keeps the result
+it earned on its own.
+
+Refused rather than downgraded, because both silent behaviours are worse than
+an error. Honouring `true` ships an experimental feature with a veto over every
+build. Ignoring it leaves a project believing its build is gated on a notifier
+when nothing is — the "accepted and does nothing" shape this design rejects
+everywhere else (`loop` on a self-closing event, `timeout_seconds` on
+`during_build`), so it would be inconsistent to make an exception for the one
+key whose wrong answer is invisible.
+
+The key stays in the schema so manifests do not have to change when the feature
+is promoted, and the mechanism under it already implements both values — the
+`sideEffect == true` branch in `mcpp.hooks` is unreachable today ON PURPOSE.
+**Promotion is the deletion of one block in the parser**, not a
+reconstruction. That is the property to preserve when editing either side.
+
+Two further limits are permanent rather than provisional and should not be read
+as part of the experiment:
+
+- Only the ROOT project's hooks run. A dependency's `[hooks]` is inert by
+  construction — there is exactly one `Span` construction and there are exactly
+  two `invoke` call sites, all in `run_build_with_hooks`, all fed from the
+  context's own manifest.
+- Only `mcpp build` runs hooks. `mcpp run`, `mcpp test` and
+  `mcpp build --configure-only` build too, and deliberately do not.
+
 ## Criteria
 
 The assertions this design has to earn are about *state*, not about log lines —
@@ -202,3 +233,7 @@ The assertions this design has to earn are about *state*, not about log lines 
    rather than papered over with a test that passes vacuously.
 7. **A self-closing event rejects `loop`.** Otherwise the key is accepted,
    does nothing, and the user concludes the feature does not work.
+8. **`side_effect = true` is refused, and every failure mode is a warning.**
+   Two assertions, not one: the exit code says the hook had no vote, and the
+   warning says the failure was not swallowed. A test that checked only the
+   exit code would pass just as well if hooks had stopped running altogether.

docs/05-mcpp-toml.md

@@ -2094,7 +2094,15 @@ See [07 — build.mcpp](07-build-mcpp.md). Naming such a file in
 command: nothing tracks it, and editing the file produces `ninja: no work to
 do`.
 
-### 2.16 `[hooks]` — Project Build Lifecycle Commands
+### 2.16 `[hooks]` — Project Build Lifecycle Commands (experimental)
+
+> **Experimental.** A hook cannot currently decide whether a build succeeded.
+> Every hook failure is reported as a **warning** and `mcpp build` keeps the
+> result it earned on its own; `side_effect = true` is refused with an error
+> rather than honoured. The key stays in the schema so that manifests written
+> today do not have to change when the feature is promoted. Two further limits
+> are permanent rather than provisional: only the root project's hooks run, and
+> only `mcpp build` runs them.
 
 A hook is a command `mcpp build` **owns for an interval**, and the event names
 the interval:
@@ -2111,7 +2119,7 @@ during_build = { cmd = "mcpp-hooks-audioplayer bgm", loop = true }
 # Optional; these are the defaults.
 timeout_seconds = 10
 enabled = true
-side_effect = true
+side_effect = false           # `true` is refused while this is experimental
 ```
 
 | Key | Type | Default | The interval it names |
@@ -2122,7 +2130,7 @@ side_effect = true
 | `during_build` | command | — | Opens before the build, closes after it |
 | `timeout_seconds` | integer, 1–86400 | `10` | Bounds one run of a command |
 | `enabled` | bool | `true` | Enables all commands in this table |
-| `side_effect` | bool | `true` | Whether a hook failure makes the overall build fail |
+| `side_effect` | bool | `false` | Whether a hook failure makes the build fail. **Reserved** — only `false` is accepted while this is experimental |
 
 The first three intervals are **self-closing** — they end when the command
 does. "Synchronous" is not a separate mode here; it is what a self-closing
@@ -2172,11 +2180,24 @@ hook failure. For `during_build` there is one more: a looped command that
 **fails to stay up** — five consecutive runs ending unsuccessfully within a
 second — stops being restarted and is reported. (A command that finishes
 quickly and *successfully* is doing exactly what `loop` was asked to repeat,
-and is not a failure.) With `side_effect = false`, mcpp reports a warning and
-preserves the build's result; with `true`, it returns failure — but a build that
-failed on its own keeps its own exit code, so `mcpp build` never reports a
-compile error as a notifier problem. A hook's own failure does not trigger
-another hook.
+and is not a failure.) Every one of those is reported as a **warning**, and the
+build keeps the result it earned on its own — while `[hooks]` is experimental
+it does not get a vote. A hook's own failure does not trigger another hook.
+
+`side_effect = true` is what will change that, and asking for it today is an
+error:
+
+```text
+error: mcpp.toml: error: [hooks].side_effect = true is not available yet:
+[hooks] is experimental and cannot decide whether a build succeeded. …
+```
+
+Refused rather than quietly downgraded, because both silent options are worse:
+honouring it would give an experimental feature a veto over every build, and
+ignoring it would leave a project believing its build is gated on a notifier
+when nothing is. When the feature is promoted, `true` will mean "a hook failure
+fails the build" — and a build that failed on its own will still keep its own
+exit code, so `mcpp build` never reports a compile error as a notifier problem.
 
 Two things are worth knowing about a `during_build` command specifically:
 
@@ -2197,9 +2218,11 @@ Scope, precisely:
   each member in turn — its own `[hooks]`, around its own build, in its own
   root. A *virtual* workspace root (`[workspace]` with no `[package]`) builds
   nothing, so a `[hooks]` table there never fires.
-- A dependency's `[hooks]` is never run. Only the root project's — installing a
-  package cannot make its author's shell command part of the consuming
-  project's build.
+- A dependency's `[hooks]` is **skipped**, always. Only the root project's run.
+  Every manifest mcpp parses carries the section, a dependency's included, and
+  nothing reads it — which is what keeps `mcpp add` from meaning "run this
+  author's shell command on my next build". This is a property of the design,
+  not a default awaiting a switch.
 - Declaring an active hook opts the project out of the no-op fast path, because
   `build_start` is specified to run after preparation. Expect `mcpp build` on an
   already-current hooked project to cost a preparation pass rather than
@@ -2231,9 +2254,11 @@ side_effect = false
 deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
 ```
 
-Background music for the length of the build, a different sound for how it
-ended, and `side_effect = false` so that a missing audio device is a warning
-rather than a failed build.
+Background music for the length of the build, and a different sound for how it
+ended. `side_effect = false` is written out rather than left to the default:
+it is the value this manifest wants on its own terms — a missing audio device
+should never fail a build — so it will still say so once the key has more than
+one accepted value.
 
 ## Appendix A. Schema Ownership Principle (admission criteria for new fields)
 

docs/zh/05-mcpp-toml.md

@@ -1791,7 +1791,13 @@ o.arg("./mkblob.sh").arg("blob.bin").arg("${mcpp.out_dir}/blob.o")
 但 ldflags 是链接命令里的一串字符:没有任何东西跟踪它,改了它得到的是
 `ninja: no work to do`。
 
-### 2.16 `[hooks]` —— 项目构建生命周期命令
+### 2.16 `[hooks]` —— 项目构建生命周期命令(实验性)
+
+> **实验性。** Hook 目前**不能**决定一次构建成功与否。所有 Hook 失败都以
+> **warning** 报出,`mcpp build` 保留它自己挣来的结果;`side_effect = true`
+> 会被报错拒绝,而不是被采纳。这个键保留在 schema 里,这样今天写下的 manifest
+> 在该功能转正时无需改动。另有两条限制是永久的、不是临时的:**只有根项目的 Hook
+> 会执行**,而且**只有 `mcpp build` 会执行它们**。
 
 Hook 是 `mcpp build` **在一段区间内持有**的命令,事件名就是那段区间:
 
@@ -1807,7 +1813,7 @@ during_build = { cmd = "mcpp-hooks-audioplayer bgm", loop = true }
 # 可选;以下是默认值。
 timeout_seconds = 10
 enabled = true
-side_effect = true
+side_effect = false           # 实验期内 `true` 会被拒绝
 ```
 
 | 键 | 类型 | 默认值 | 它命名的区间 |
@@ -1818,7 +1824,7 @@ side_effect = true
 | `during_build` | 命令 | — | 构建开始前开启,构建结束后闭合 |
 | `timeout_seconds` | 整数,1–86400 | `10` | 单次运行的时限 |
 | `enabled` | 布尔 | `true` | 是否启用本表中的全部命令 |
-| `side_effect` | 布尔 | `true` | Hook 失败是否让本次构建失败 |
+| `side_effect` | 布尔 | `false` | Hook 失败是否让本次构建失败。**保留键**——实验期内只接受 `false` |
 
 前三个区间是**自闭合**的——命令退出,区间就结束。"同步"在这里不是一种单独的模式,
 它就是自闭合区间的样子。`during_build` 是唯一由别的东西闭合的区间,而那两个只对其中
@@ -1858,10 +1864,21 @@ build_start
 
 命令无法启动、返回非零或超过时限均视为 Hook 失败。`during_build` 还多一种:开了 `loop`
 的命令**起不来**——连续五次在一秒内以非零状态结束——就不再重启,并被报出来。(很快就
-成功结束的命令,正是 `loop` 被要求重复的那件事,不算失败。)`side_effect = false` 时
-mcpp 报 warning 并保留原构建结果;设为 `true` 时返回失败——但构建自身失败时保留它自己
-的退出码,所以 `mcpp build` 不会把一次编译错误报成通知程序的问题。Hook 自身失败不会再
-触发另一个 Hook。
+成功结束的命令,正是 `loop` 被要求重复的那件事,不算失败。)以上每一种都以 **warning**
+报出,构建保留它自己挣来的结果——`[hooks]` 还在实验期,它没有投票权。Hook 自身失败不会
+再触发另一个 Hook。
+
+改变这一点的正是 `side_effect = true`,而今天写它是一个错误:
+
+```text
+error: mcpp.toml: error: [hooks].side_effect = true is not available yet:
+[hooks] is experimental and cannot decide whether a build succeeded. …
+```
+
+是拒绝而不是悄悄降级,因为两种沉默的做法都更糟:采纳它等于让一个实验性功能对每一次
+构建都有否决权;忽略它则让项目以为自己的构建被通知程序把着关,而实际上没有。功能转正
+后,`true` 的含义是"Hook 失败让构建失败"——而构建自身失败时仍保留它自己的退出码,所以
+`mcpp build` 不会把一次编译错误报成通知程序的问题。
 
 关于 `during_build` 有两件事值得单独知道:
 
@@ -1878,8 +1895,9 @@ mcpp 报 warning 并保留原构建结果;设为 `true` 时返回失败——但
 - Hook 属于**被构建的那个包**。workspace 展开时就是逐个成员:各自的 `[hooks]`、
   各自的构建、各自的根目录。**虚拟** workspace 根(只有 `[workspace]` 没有
   `[package]`)不构建任何东西,写在那里的 `[hooks]` 永不触发。
-- 依赖的 `[hooks]` 永不执行,只有根项目的会——装一个包不会把包作者的 Shell 命令
-  变成消费方构建的一部分。
+- 依赖的 `[hooks]` **一律跳过**,只有根项目的会执行。mcpp 解析的每一份 manifest 都
+  带着这一节,依赖的也带,而没有任何东西去读它——这正是"装一个包"不会变成"在我下次
+  构建时跑包作者的 Shell 命令"的原因。这是设计的性质,不是一个等着被打开的默认值。
 - 声明了生效的 Hook 就等于让项目放弃空转快路径,因为 `build_start` 规定在准备阶段之后
   执行。对已经是最新状态的带 Hook 项目,`mcpp build` 的代价是一次准备,而不是毫秒级。
 
@@ -1906,8 +1924,9 @@ side_effect = false
 deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
 ```
 
-构建全程的背景音乐,加上一段区分结果的提示音;`side_effect = false` 让缺少音频设备
-只是一条 warning,而不是一次失败的构建。
+构建全程的背景音乐,加上一段区分结果的提示音。`side_effect = false` 写出来而不是靠
+默认值:它是这份 manifest 自己就想要的值——缺个音频设备不该让构建失败——所以等这个键
+有了不止一个可接受的值之后,它仍然会这么写。
 
 ## 附录 A. Schema 所有权原则(新字段准入标准)
 

modules/manifest/src/toml.cppm

@@ -1651,6 +1651,26 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             *out = it->second.as_bool();
         }
 
+        // ⚠️ THE EXPERIMENTAL GATE, AND THE WHOLE OF IT.
+        //
+        // `[hooks]` is experimental, so it may not decide whether a build
+        // succeeded. Asking for `side_effect = true` is refused rather than
+        // downgraded, because the two possible silent behaviours are both
+        // worse than an error: honouring it ships an experimental feature with
+        // a veto over every build, and ignoring it leaves a project believing
+        // its build is gated on a notifier when nothing is.
+        //
+        // Everything under this line already implements both values. Deleting
+        // this block is what promoting the feature consists of.
+        if (m.hooks.sideEffect)
+            return std::unexpected(error(origin,
+                "[hooks].side_effect = true is not available yet: [hooks] is "
+                "experimental and cannot decide whether a build succeeded. A "
+                "failing hook is reported as a warning and the build keeps its "
+                "own result. Remove the key (the default is false) — it is "
+                "reserved so that manifests do not have to change when the "
+                "feature is promoted."));
+
         static constexpr std::string_view kKnownHookKeys[] = {
             "build_start", "build_failed", "build_finished", "during_build",
             "timeout_seconds", "enabled", "side_effect",

modules/manifest/src/types.cppm

@@ -971,9 +971,20 @@ struct Hooks {
 
     int         timeoutSeconds = 10;   // default for one run of a hook command
     bool        enabled        = true; // whole table
-    // Whether a hook failure fails the build. False downgrades it to a
-    // warning and preserves whatever the build itself returned.
-    bool        sideEffect     = true;
+
+    // ⚠️ EXPERIMENTAL: FALSE, AND CURRENTLY THE ONLY VALUE.
+    //
+    // The key means "a hook failure fails the build". While `[hooks]` is
+    // experimental it does not get to decide that: a hook that fails is
+    // reported as a warning and the build keeps whatever result it earned on
+    // its own. `side_effect = true` is REJECTED by the parser rather than
+    // accepted and ignored — a project that believes its build is gated on a
+    // notifier, and is not, has been told something false.
+    //
+    // The mechanism below it is intact and is what the key will switch on when
+    // the feature graduates; the parser check is the whole of the gate, so
+    // removing it is the whole of the change.
+    bool        sideEffect     = false;
 
     // "This project has work for `mcpp build` to do." Distinct from `enabled`:
     // a table that only sets policy keys declares no command, and must leave

src/hooks.cppm

@@ -1,5 +1,10 @@
 // mcpp.hooks — running the project's `[hooks]` lifecycle commands.
 //
+// ⚠️ EXPERIMENTAL. A hook cannot currently change whether a build succeeded:
+// every failure is a warning, and `side_effect = true` is refused by the
+// manifest parser. Only the ROOT project's hooks are ever run — a dependency's
+// `[hooks]` is inert. See docs/05-mcpp-toml.md §2.16.
+//
 // The CONFIGURATION is not parsed here: `[hooks]` is a section of mcpp.toml
 // and mcpp.toml has one parser (mcpp.manifest). What lives here is the part
 // that is policy rather than grammar — when a command runs, what a failure
@@ -72,7 +77,7 @@ private:
     bool                  declared_      = false;
     bool                  started_       = false;
     bool                  closed_        = false;
-    bool                  sideEffect_    = true;
+    bool                  sideEffect_    = false;
     bool                  ok_            = true;
     std::atomic<bool>     stop_{false};
     std::atomic<bool>     gaveUp_{false};
@@ -125,6 +130,13 @@ event_command(const mcpp::manifest::Hooks& hooks, Event event) {
 // four of them (cannot start, non-zero, timed out, failed to stay up). The
 // message is identical either way; only its severity and the build's fate
 // differ.
+//
+// ⚠️ WHILE `[hooks]` IS EXPERIMENTAL, `sideEffect` IS ALWAYS FALSE — the
+// manifest parser refuses `side_effect = true` (see
+// modules/manifest/src/toml.cppm). The `true` branch below is therefore
+// unreachable today ON PURPOSE: it is the behaviour the key will select when
+// the feature is promoted, and keeping it here means promotion is a deletion
+// in the parser rather than a reconstruction here.
 bool report_hook_failure_flag(bool sideEffect, const std::string& message) {
     if (sideEffect) {
         mcpp::ui::error(message);