b1e8a74708
* fix(#1196): wire discuss loop step for capability hooks discuss was contract-declared (gsd:loop-host marker, in POINT_ORDER and LOOP_HOST_CONTRACT) but structurally unwireable: discuss-phase.md had no `loop render-hooks` dispatch and was absent from the conformance gate's HOST_LOOP_FILES, so capabilities could never wire discuss:pre/discuss:post. - discuss-phase.md: add minimal discuss:pre (before analyze_phase) and discuss:post (after write_context) render-hooks dispatch steps that delegate consumption to a new shared reference (kept under the 32KB #2551 budget; no inline subagent dispatch token). - references/loop-hook-dispatch.md: new canonical, point-agnostic contract for consuming `loop render-hooks --raw` activeHooks (contribution/step/ gate) — single source for hook consumption across host loops. - gen-loop-host-contract.cjs: derive HOST_LOOP_FILES from STEP_WORKFLOWS and export scanWiredPoints()/getWiredLoopPoints() (throws on a missing host file) — one source of truth for the host-loop file + wired-point set. - phase6-capstone-conformance.test.cjs: consume the derived HOST_LOOP_FILES and shared scanWiredPoints (was a hand-maintained duplicate omitting discuss-phase.md + a duplicated regex). - gen-capability-registry.cjs: add validateHooksWired() gen-time guard that rejects a capability hook declared at a valid-but-unwired loop point, with a clear remediation message — failure now surfaces at gen --check/--write time instead of deep in the full conformance suite. - tests (capability-registry.test.cjs): regression + anti-pattern parity guards (every loop-host marker is in STEP_WORKFLOWS/HOST_LOOP_FILES; POINT_ORDER === flattened LOOP_HOST_CONTRACT) so no step can drift into the discuss-class gap again. - docs/INVENTORY*: register the new reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(#1196): backfill changeset PR number (#1199) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# Loop Hook Dispatch Contract
|
|
|
|
Generic reference for consuming the `--raw` JSON output of `gsd_run loop render-hooks <point>`
|
|
in any host-loop workflow. This document is point-agnostic — it applies to every loop
|
|
extension point (discuss:pre, discuss:post, plan:pre, plan:post, execute:pre, execute:wave:pre,
|
|
execute:wave:post, execute:post, verify:pre, verify:post, ship:pre, ship:post).
|
|
|
|
## Envelope shape
|
|
|
|
```json
|
|
{
|
|
"point": "discuss:pre",
|
|
"activeHooks": [
|
|
{ "kind": "contribution", "into": "orchestrator", "fragment": { "inline": "..." } },
|
|
{ "kind": "step", "ref": { "skill": "my-skill" } },
|
|
{ "kind": "gate", "check": { "query": "..." }, "blocking": true, "onError": "skip" }
|
|
],
|
|
"rendered": "..."
|
|
}
|
|
```
|
|
|
|
`activeHooks` is an array of enabled hook entries for the named point. It is empty (or absent)
|
|
when no capability has registered an active hook at this point — treat that as a no-op.
|
|
|
|
## Dispatch rules by `kind`
|
|
|
|
### `contribution`
|
|
|
|
Inject `fragment.inline` verbatim into the context for the role named in `into`
|
|
(e.g. `orchestrator`, `planner`). Do not paraphrase — the text is the product.
|
|
|
|
### `step`
|
|
|
|
Dispatch the referenced unit:
|
|
|
|
- `ref.skill` present → dispatch via the Skill tool with skill id `gsd-<ref.skill>`.
|
|
- `ref.agent` present → dispatch via the Agent tool with `subagent_type` = `ref.agent`.
|
|
Before dispatching an agent, print the canonical liveness banner so users know silence
|
|
is expected and do not kill a healthy agent:
|
|
|
|
```
|
|
◆ Spawning <agent>... (runs in a subagent — no output until it returns; expected, not a freeze)
|
|
```
|
|
|
|
Wait for the result before continuing to the next hook or the next step.
|
|
|
|
### `gate`
|
|
|
|
Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `blocking`:
|
|
|
|
- `blocking: true` → if the check returns `block: true`, surface `check.message` to the user
|
|
and stop the current step. Do not continue.
|
|
- `blocking: false` → advisory only; surface the message but continue regardless of outcome.
|
|
|
|
Honor `onError` if the check itself errors: `skip` means treat as non-blocking and continue;
|
|
`fail` means surface the error and stop.
|
|
|
|
## Empty / absent `activeHooks`
|
|
|
|
If `activeHooks` is absent, null, or an empty array, skip silently and continue to the next
|
|
step in the workflow. No output to the user is needed.
|