msd-core/docs/reference/review-verification-capabilities.md

Review and Verification Capabilities

This reference describes the Capability Registry declarations used by MSD review and verification features in MSD 1.5 and later. It covers the first migrated review/verification capabilities from ADR-857 Phase 6: code review, security enforcement, and Nyquist validation.

For the system design, see ADR-857: Capability system.

Terms

Capability: A feature bundle declared in capabilities/<id>/capability.json. A capability owns skills, agents, config keys, and loop hooks.

Loop Extension Point: A named point in the Discuss -> Plan -> Execute -> Verify -> Ship loop where capabilities can register hooks.

Step hook: A hook that runs a capability skill as an ordered step.

Contribution hook: A hook that injects guidance into a core workflow prompt.

Gate hook: A hook that evaluates a predicate and can block when blocking is true.

Capability Ownership

Capability	Skills	Agents	Config keys
code-review	code-review	msd-code-reviewer, msd-code-fixer	workflow.code_review, workflow.code_review_depth
security	secure-phase	msd-security-auditor	workflow.security_enforcement, workflow.security_asvs_level, workflow.security_block_on
nyquist	validate-phase	msd-nyquist-auditor	workflow.nyquist_validation

These keys are Capability-owned config keys. They remain valid for .planning/config.json, but they are not central schema keys; validation and defaults come from the generated Capability Registry. Workflows must not branch directly on the boolean activation keys. Workflows resolve activation by calling msd-tools loop render-hooks <point>.

Hook Map

Point	Capability	Kind	Behavior
plan:pre	security	contribution	Adds threat-model guidance to planner context when security enforcement is active.
execute:post	code-review	step	Runs post-execution code review when code review is active.
verify:post	security	step	Runs security verification and produces SECURITY.md when security enforcement is active.
verify:post	nyquist	step	Runs validation coverage audit and produces VALIDATION.md when Nyquist validation is active.
ship:pre	security	gate	Blocks shipping unless SECURITY.md reports threats_open: 0.

Activation Rules

Workflows use the active hook list from the registry:

EXECUTE_POST_HOOKS_JSON=$(msd_run loop render-hooks execute:post --raw)
VERIFY_POST_HOOKS_JSON=$(msd_run loop render-hooks verify:post --raw)

The resolver evaluates each hook's when key against the project config and the capability config default. If the key is absent and the capability declaration default is true, the hook is configured on.

A hook is active only when both conditions are true:

• The Capability is enabled by the resolved Capability State: installed by .msd-profile and surfaced by .msd-surface.json.
• The hook is configured on by its when key.

Use the diagnostic state view to inspect the same answer the workflows consume:

msd-tools capability state --config-dir ~/.claude --raw

In that output, configured reflects config/default resolution, while active reflects final participation after install and surface state. Disabling a migrated Capability at the runtime surface removes its active hooks even when the project config default is true.

Direct command workflows self-gate the same way:

• /msd-code-review resolves the active execute:post hook whose ref.skill == "code-review".
• /msd-secure-phase resolves the active verify:post hook whose ref.skill == "secure-phase".
• /msd-validate-phase resolves the active verify:post hook whose ref.skill == "validate-phase".

Authoring Notes

When adding a review or verification capability:

1. Declare owned skills, agents, config keys, and hooks in capabilities/<id>/capability.json.
2. Use unprefixed skill stems in ref.skill; workflows add the msd- prefix when invoking skills.
3. Declare produces and consumes arrays for every step and contribution hook.
4. Use onError: "halt" for verification work that must stop advancement when it fails.
5. Use a blocking gate for ship-time predicates that must prevent release.
6. Regenerate msd-core/bin/lib/capability-registry.cjs with npm run gen:capability-registry.
7. Add tests that prove disabled hooks are absent from loop render-hooks output and that workflows do not branch directly on the capability's activation config key.

Do not add third-party code loading through a capability declaration. ADR-857 reserves that trust boundary for a separate design.