fix(#3606): validate hook-kind coverage at call sites and dispatch generically (#3687)

* test(#3606): pin hook-kind coverage in the wired guard

* fix(#3606): validate hook-kind coverage at call sites and dispatch generically

* fix(#3606): address review - segment-granular narrowing, zero-coverage diagnosis, quick.md, fragment extraction

* fix(#3606): drop stale shrink-ack, export HOOK_GROUP_KINDS, dedupe scanner regex

* chore(#3606): regenerate install-tree fixtures for new wave-post fragment

* chore(#3606): sync canonical launcher preamble into new fragment

* fix(#3606): keep fragment preamble ahead of first gsd_run mention

* fix(#3606): revert sync script's preamble move in explore.md

* chore(#3606): regenerate derived manifests post-rebase

* chore(#3606): allowlist peer test files - base was red on the count lane

* chore(#3606): regenerate inventory for peer's verify-command-grounding doc

* chore(#3606): grounding test maps to its own module by longest prefix

* chore(#3606): backfill changeset pr number

---------

Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
2026-08-19 16:41:27 -04:00
committed by GitHub
parent 79781e68eb
commit ea594300d9
35 changed files with 546 additions and 86 deletions

View File

@@ -3435,26 +3435,55 @@ function topoSortContributions(entries) {
// ─── Gen-time wired guard ─────────────────────────────────────────────────────
/**
* Hook group (capability.json array name) → hook kind (dispatch discriminator).
* Single source of truth for both validateHooksWired and the scanner-parity
* test in tests/capability-registry.test.cjs (#3606).
*/
const HOOK_GROUP_KINDS = Object.freeze({
steps: 'step',
contributions: 'contribution',
gates: 'gate',
});
/**
* Validate that every hook point declared by a capability has a corresponding
* `loop render-hooks <point>` call site in one of the host-loop workflow files.
* `loop render-hooks <point>` call site in one of the host-loop workflow files,
* AND — #3606 — that the call site's dispatch text covers the hook's KIND.
*
* A call site proves hooks are rendered, not dispatched: a consumer that
* iterates only `kind == "gate"` (or narrows `kind == "step"` to one
* `ref.skill`) silently drops every other registered kind — a capability can
* be wired, enabled, resolved active, and never run. See
* gsd-core/references/loop-hook-dispatch.md ("A point whose workflow
* hand-rolls one kind does not implement this contract").
*
* Only valid loop points (in VALID_LOOP_POINTS) are checked here. Invalid points
* are already caught by validateStep/validateContribution/validateGate — do not
* double-report.
*
* KNOWN LIMITATION (#3606): coverage is the UNION across all call sites for a
* point in the five STEP_WORKFLOWS host files. Consumers outside that universe
* (quick.md, autonomous.md, code-review*.md, audit-milestone.md,
* secure-phase.md, validate-phase.md) are not per-file checked — a narrowed
* consumer there passes as long as one host file covers the point. Per-file
* coverage maps are the tightening path.
*
* @param {object} cap Validated capability object.
* @param {Set<string>} wiredSet Set of points that have call sites in host workflows.
* @returns {string[]} Array of error strings; empty means all points are wired.
* @param {Map<string, Set<string>>} wiredKinds Per point, the hook kinds the
* host workflows' call-site dispatch text covers (getWiredKinds). A point
* absent from the map is unwired.
* @returns {string[]} Array of error strings; empty means all points
* are wired and every registered kind is covered.
*/
function validateHooksWired(cap, wiredSet) {
function validateHooksWired(cap, wiredKinds) {
const errors = [];
const capId = cap.id || '(unknown)';
function checkPoint(point, groupName, idx) {
function checkPoint(point, groupName, kind, idx) {
// Only flag valid points that are unwired — invalid points are schema-validator's job.
if (!VALID_LOOP_POINTS.has(point)) return;
if (!wiredSet.has(point)) {
if (!wiredKinds.has(point)) {
errors.push(
'capability "' + capId + '" ' + groupName + '[' + idx + '].point "' + point +
'" is declared but not wired in any host-loop workflow ' +
@@ -3462,20 +3491,34 @@ function validateHooksWired(cap, wiredSet) {
'Wire the call site in the host workflow ' +
'(see scripts/gen-loop-host-contract.cjs STEP_WORKFLOWS) or remove the hook.',
);
return;
}
const covered = wiredKinds.get(point);
if (covered.size === 0) {
errors.push(
'capability "' + capId + '" ' + groupName + '[' + idx + '].point "' + point +
'" has `loop render-hooks ' + point + '` call site(s), but their dispatch text covers NO ' +
'hook kind — every consumer is narrowed to specific hooks. Dispatch every registered kind ' +
'per gsd-core/references/loop-hook-dispatch.md.',
);
return;
}
if (!covered.has(kind)) {
errors.push(
'capability "' + capId + '" ' + groupName + '[' + idx + '].point "' + point +
'" registers a ' + kind + ' hook, but the host call site\'s dispatch text never ' +
'covers `kind == "' + kind + '"` (it covers: ' + [...covered].sort().join(', ') + '). ' +
'A hand-rolled single-kind consumer silently never dispatches the other kinds — ' +
'dispatch every registered kind per gsd-core/references/loop-hook-dispatch.md.',
);
}
}
for (let i = 0; i < (cap.steps || []).length; i++) {
const hook = cap.steps[i];
if (hook.point !== undefined) checkPoint(hook.point, 'steps', i);
}
for (let i = 0; i < (cap.contributions || []).length; i++) {
const hook = cap.contributions[i];
if (hook.point !== undefined) checkPoint(hook.point, 'contributions', i);
}
for (let i = 0; i < (cap.gates || []).length; i++) {
const hook = cap.gates[i];
if (hook.point !== undefined) checkPoint(hook.point, 'gates', i);
for (const [group, kind] of Object.entries(HOOK_GROUP_KINDS)) {
for (let i = 0; i < (cap[group] || []).length; i++) {
const hook = cap[group][i];
if (hook.point !== undefined) checkPoint(hook.point, group, kind, i);
}
}
return errors;
@@ -3699,6 +3742,7 @@ module.exports = {
topoSortSteps,
topoSortContributions,
validateHooksWired,
HOOK_GROUP_KINDS,
validateConfigSliceEntry,
classifyCrossErrors,
runConfigFormatParityGate,