feat(hooks): define portable workspace and plugin hook distribution

HVE Core needs a supported contract for hooks that can be used directly from the repository and distributed through agent plugins. These execution contexts have different path semantics:

* Workspace hooks are discovered from configured `.github/hooks` locations. They do not receive a plugin-root environment variable and commonly resolve commands relative to the workspace.
* Distributed plugin hooks run outside the workspace. VS Code supplies the installed plugin directory through plugin-root placeholders and environment variables, and relative workspace paths are not reliable.

This distinction surfaced through the telemetry hook. Its original Bash command used `${CLAUDE_PLUGIN_ROOT:-.}` to bridge both contexts. VS Code plugin placeholders support exact tokens, not shell modifiers, and distributed use produced warnings such as:

```text
/bin/sh: 1: ../.github/hooks/shared/telemetry/telemetry-collector.sh: not found
```

The initial diagnosis attributed the warning to omitted runtime scripts. A subsequent experiment replaced the expression with the exact `${CLAUDE_PLUGIN_ROOT}` placeholder. Current VS Code documentation establishes that this token is valid for Copilot-format plugin hooks and expands to the installed plugin directory.

That experiment then failed when the same manifest was loaded as a workspace hook, because no plugin-root value exists in that context. The exact token resolved to an empty value and produced `/.github/...`.

These results show that repository use and plugin distribution need an explicit portability design. Potential approaches include runtime environment detection, separate workspace and plugin manifests backed by shared scripts, or adoption of the Agent Plugins namespaced hook layout. The design also needs to account for plugin packaging closure, multiple future hook packages, cross-platform command forms, and repeatable tests of both loading contexts.

There is no immediate telemetry dependency on this work. PR #2719 retires the ambient telemetry hook in favor of opt-in capture and should resolve the current user-facing telemetry warnings. This item records the broader capability needed before HVE Core distributes future hooks.

## Discovery Notes

* `${CLAUDE_PLUGIN_ROOT}` is supported for Copilot-format plugin hooks in VS Code.
* Placeholder expansion requires an exact token; shell modifiers are not part of the documented placeholder syntax.
* Plugin execution also supplies `CLAUDE_PLUGIN_ROOT` as an environment variable.
* Workspace hook execution does not supply a plugin root.
* A manifest enabled through `chat.hookFilesLocations` can therefore require a different path strategy from the same manifest loaded through a plugin.
* Local shell simulations indicate that runtime environment detection can resolve both roots, but this has not been verified through a clean installed-plugin lifecycle and is not yet the selected design.

## Acceptance Criteria

* [ ] Document the supported workspace and distributed-plugin hook execution contexts, including their root variables, working-directory guarantees, and path-resolution differences.
* [ ] Select and document a canonical repository layout and command strategy for hooks that must support both contexts.
* [ ] Define how multiple package-scoped hook manifests are composed into the single hook configuration supported by a plugin.
* [ ] Define and validate the distribution closure for each hook manifest, including every referenced script and runtime support file.
* [ ] Reject unsupported placeholder syntax, path escapes, and references to files that are absent from the distributed plugin.
* [ ] Add automated Bash and PowerShell tests for workspace-hook and clean installed-plugin execution.
* [ ] Update contributor documentation with the selected authoring, packaging, local-testing, and validation workflow.
* [ ] Keep telemetry retirement and opt-in telemetry implementation in #2717 and PR #2719 rather than making them prerequisites for this work.

## Non-Goals

* Repairing or retaining the ambient telemetry hook.
* Delaying PR #2719 while the general hook distribution design is developed.
* Registering a new distributed hook before the portability contract and tests are in place.

## Related

* Telemetry retirement: #2717
* Telemetry retirement implementation: #2719
* Related Copilot CLI and Windows failure: #2496

Start by inventorying the configured `.github/hooks` locations, the telemetry hook path, and the `chat.hookFilesLocations` entry point described in the issue. Compare workspace and clean installed-plugin loading, then define the layout and packaging rules. Done means the selected contract, closure validation, placeholder and path rejection, Bash and PowerShell tests, and contributor documentation satisfy the acceptance criteria.

Written by the indexing model from the issue text.