Document setup hooks boundary

CHANGELOG.md

@@ -9,6 +9,8 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ### Added
 
+- Added documentation for the no-hooks manifest boundary and future setup hook
+  criteria.
 - Added the design target for a future structured `python:` manifest section.
 - Added the user-local IDE preference design for `~/.base.d/config.yaml`.
 - Added documentation guidance for using `mise` with Go and Java projects.

README.md

@@ -206,9 +206,11 @@ Maven or Gradle project files. Base does not need first-class `go-package` or
 `java-package` artifact types until it has a Base-specific behavior to add on
 top of those native ecosystems.
 
-Base should not run arbitrary setup hooks until there is an explicit,
-reviewable contract for when they run, where they run, whether they are
-interactive, and how dry-run/check/doctor report them.
+Base does not run arbitrary setup hooks from the manifest. Projects should use
+typed Base contracts or project-owned installers/tasks until there is an
+explicit, reviewable hook contract for when hooks run, where they run, whether
+they are interactive, and how dry-run/check/doctor report them. See
+[Setup Hooks Boundary](docs/setup-hooks.md).
 
 The curated tool artifact registry lives in `cli/python/base_setup/registry.py`.
 It should stay small and Base-aware. `python-package` artifacts are pass-through

docs/README.md

@@ -44,6 +44,8 @@ reference. The filename should answer "what is this about?"
 - [Python Manifest Section](python-manifest.md) records the future structured
   Python manifest shape and its relationship to current `python-package`
   artifacts.
+- [Setup Hooks Boundary](setup-hooks.md) records why Base does not support
+  arbitrary manifest setup hooks yet.
 - [`basectl onboard`](basectl-onboard.md) captures the guided setup experience
   and its relationship to project installers.
 - [`basectl ci`](basectl-ci.md) defines the future non-interactive CI entry

docs/architecture.md

@@ -360,7 +360,8 @@ orchestration actions. The design rule is delegation-first:
   reconciliation.
 - Do not run arbitrary project setup hooks until Base has a clear safety
   contract for execution timing, dry-run behavior, interactivity, and
-  diagnostics.
+  diagnostics. See [setup-hooks.md](setup-hooks.md) for the current no-hooks
+  decision and future reconsideration criteria.
 
 Base owns the curated tool artifact registry only for things it must manage
 directly. The current registry is `cli/python/base_setup/registry.py`.

docs/project-installers.md

@@ -41,6 +41,8 @@ A project installer owns:
 - cloning or updating the project repository
 - installing or locating Base
 - calling Base commands in the right order
+- imperative setup steps that are not yet covered by a typed Base manifest
+  contract
 - explaining next steps after setup succeeds or fails
 
 The installer should not reimplement Base's setup logic. It should call Base.

docs/setup-hooks.md

@@ -0,0 +1,74 @@
+# Setup Hooks Boundary
+
+Base should not support arbitrary setup hooks in `base_manifest.yaml` right now.
+
+This is a deliberate safety and product-boundary decision. Base setup should be
+declarative, inspectable, idempotent, and diagnosable. Arbitrary hooks would let
+projects run imperative shell code during setup before Base has a clear contract
+for timing, dry-run behavior, interactivity, logging, failure handling, and
+security review.
+
+## Current Decision
+
+Do not add fields such as:
+
+```yaml
+hooks:
+  post_setup:
+    - ./scripts/bootstrap.sh
+```
+
+Instead, use the typed contracts Base already understands:
+
+- `brewfile` for ordinary Homebrew packages and casks
+- `mise` for language runtimes, tool versions, environment variables, and tasks
+- `ide` for supported IDE app, extension, and settings bootstrap
+- `artifacts` for Base-managed artifacts
+- `test.command` or `test.mise` for project-owned test execution
+
+When a project needs a product-specific guided installer or imperative
+bootstrap, that logic should live in the project repository, for example:
+
+```text
+<project>/install.sh
+```
+
+That installer can explain product-specific context, clone or update repos,
+handle project-specific credentials, and call Base commands in the right order.
+See [project-installers.md](project-installers.md).
+
+## Rationale
+
+Unconstrained hooks create ambiguity Base cannot currently resolve:
+
+- `basectl setup --dry-run` would need to know whether a hook is safe to skip,
+  print, partially inspect, or emulate.
+- `basectl check` and `basectl doctor` would need structured diagnostics for
+  hook-owned state.
+- Interactive hooks could block non-interactive setup and future CI flows.
+- Shell snippets can hide package installs, credential prompts, network calls,
+  long-running services, and state writes outside Base's ownership boundary.
+- Hook ordering can become a hidden dependency system that is harder to reason
+  about than explicit manifest fields.
+
+Base should bias toward adding narrow, typed delegation points instead of a
+generic escape hatch.
+
+## Future Reconsideration Criteria
+
+If a real project needs hooks and typed delegation is insufficient, Base should
+first define a constrained contract. That contract must specify:
+
+- allowed phases such as `pre_setup`, `post_setup`, or `verify`
+- working directory and environment
+- whether commands are lists of arguments or shell strings
+- dry-run behavior
+- interactivity rules
+- timeout and signal behavior
+- how setup, check, doctor, and future CI report hook state
+- how failures are surfaced and whether later setup steps continue
+- whether hooks are allowed to install software, start services, or request
+  credentials
+
+Until those semantics are explicit, project-owned installers remain the correct
+place for imperative setup.