golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(#894): ADR-894 Capability declaration format + registry generation (#895)

Browse Source 
* docs(#894): ADR-894 Capability declaration format + registry generation

ADR-857 rollout phase 3a (design-only). Resolve ADR-857's deferred open
question — the on-disk Capability declaration format — as a reviewable design
ADR before any generator code.

Specifies: the capabilities/<id>/capability.json folder layout (migration-staged
ownership — declarations reference existing stems until the phase-6 move); the
capability.json schema for role:feature (skills/agents/hooks/federated config/
loopHooks) and role:runtime (the six closed projection-primitive axes); the 12
named Loop Extension Points; the gen-capability-registry.cjs generator design
(validation + cross-capability invariants + --write/--check drift gate, mirroring
gen-inventory-manifest); the generated capability-registry.cjs shape (by-id /
by-skill / by-loop-point indexes + requires-closure); and a full worked example
(the UI capability: ui-phase + ui-review + agents + config + two loop hooks).

No code — design artifact only; the generator build, federated config loader
(3b), and loop seam (3c) implement against this contract.

Closes #894

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(#894): amend ADR-894 with grilled capability declaration format

Stress-tested the declaration format before merge; the format changed
materially. Amendments:
- loopHooks[] -> three typed arrays (steps/contributions/gates), each with its
  own shape (step: ref+produces/consumes; contribution: fragment+into agent-role;
  gate: check+blocking).
- Add the Loop Host Contract (§3): each step publishes its points, agent roles,
  and core artifacts so the generator validates hooks against reality, not
  trusted strings.
- requires = capability ids only (host implicit); add tier-monotone invariant;
  drop the requires:["plan"] error from the example.
- Config federation = atomic move: a migrated key leaves the central schema in
  the same PR; presence in both is a collision (invariant stays).
- One registry, role-partitioned indexes (feature indexes vs runtimes index).
- Rework the UI worked example to the split-array shape (2 steps + 1 gate) +
  a contribution illustration.

Adds a "Grilling amendments" section recording the six changes.

* docs(#894): amend ADR-894 with round-2 grilling (operational reality)

Second design-grill round, folded in before merge:
- Loop Host Contract is GENERATED from structured workflow markers
  (<loop-point>/<agent-role>/<loop-artifact>) via gen-loop-host-contract.cjs —
  it can't drift from the real workflows.
- Hook activation `when`: cheap deterministic config-level gating evaluated by
  loop.render-hooks; deeper phase-context applicability self-gates inside the
  dispatched skill (no phase-context vocabulary to keep honest).
- `tier` is the source of install-profile + cluster membership; profiles and
  clusters are generated from tier + requires-closure (/gsd:surface operates on
  capabilities) — collapses ADR-857's multiple toggle systems.
- Gate `check` = query | declarative-predicate | agentVerdict; agentVerdict is
  forced advisory; only deterministic checks may block.
- byLoopPoint ordering is materialized in the registry; render-hooks filters the
  active set + renders. Same-capability hooks degrade gracefully when an entry
  step self-gates.
- Rollout: registry-only until atomic per-feature cutover (no double-execution
  with still-inlined workflow features).

Updates the Grilling amendments / Consequences / Alternatives / Open questions
sections; reworks the UI example with `when`.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-08 18:51:20 -04:00
committed by GitHub
parent 185935379a
commit 197d6bffe2
1 changed files with 232 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
docs/adr/894-capability-declaration-format.md Normal file
View File

@@ -0,0 +1,232 @@
# ADR-894: Capability declaration format + registry generation [Proposed]
- **Status:** Proposed
- **Date:** 2026-06-08 (amended same day across two design grillings — see "Grilling amendments")
- **Issue:** #894
- **Parent:** ADR-857 (Capability system) — resolves its Open question #1
- **Phase:** ADR-857 rollout phase 3a (design-only)
## Context
[ADR-857](857-capability-system.md) decided the **Capability** model: the five-step loop is the privileged host; every other feature is a Capability declared co-located and compiled into a generated central **Capability Registry**, owning its skills, agents, hooks, federated config-key schema, and **Loop Extension Point** registrations. ADR-857 deferred one detail to phase 3:
> *"The exact on-disk shape of a co-located Capability declaration (folder layout, declaration format)."*
The generator, the federated config loader (phase 3b), and the loop seam (phase 3c) all build against that format. This ADR fixes it **as a reviewable design** with no code, reusing the repo's proven co-located-source → generated-central pattern with a `--write`/`--check` drift gate (`scripts/gen-inventory-manifest.cjs`, `scripts/research-profiles.cjs`).
## Decision
### 1. Folder layout
```
capabilities/
<id>/
capability.json # the declaration
# (future) skills/ agents/ hooks/ loop/ — co-located owned artifacts
```
- `<id>` unique, kebab-case, equals the folder name.
- **Migration-staged ownership.** Declarations initially *reference* existing artifact locations by stem; the physical move into `capabilities/<id>/…` is the ADR-857 **phase-6 migration**. Format is identical either way.
- Genuinely shared artifacts (e.g. `gsd-planner`) stay in a core/host home and are **referenced, not owned**.
### 2. The `capability.json` schema
Schema-validated JSON. Common envelope + role-typed body (`role: feature | runtime`).
**Common envelope:**
| Field | Type | Notes |
|---|---|---|
| `id` | string (kebab) | unique; equals folder name |
| `role` | `"feature" \| "runtime"` | discriminator |
| `title`, `description` | string | label + summary |
| `tier` | `"core" \| "standard" \| "full"` | **the source of truth for install-profile + cluster membership** (§4); maps via tier + requires-closure |
| `requires` | string[] | **Capability ids only** (host is implicit). Generator enforces: exist, acyclic, **tier-monotone** (`core` may not require `standard`/`full`; `standard` may not require `full`) |
**`role: "feature"` body** — three typed hook arrays (one per ADR-857 hook kind):
| Field | Type | Notes |
|---|---|---|
| `skills` / `agents` | string[] | owned stems — exactly one owner each across all capabilities |
| `hooks` | `{event, script}[]` | lifecycle hooks |
| `config` | object | federated config-key schema slice |
| `steps` / `contributions` / `gates` | arrays | loop hooks (below) |
```jsonc
// Step — runs at a point as its own unit; order derives from produces/consumes
{ "point": "plan:pre", "ref": { "skill": "ui-phase" }, // {skill:…} | {agent:…}
"produces": ["UI-SPEC.md"], "consumes": ["CONTEXT.md"],
"when": "workflow.ui_phase", // config-level activation (§ below)
"onError": "skip" } // "skip" (default) | "halt"
// Contribution — injects a fragment into a NAMED agent role's prompt
{ "point": "plan:pre", "into": "planner", // into ∈ the step's published agentRoles
"fragment": { "path": "loop/threat-model.md" }, // {path:…} | {inline:"…"}
"when": "workflow.security_enforcement", "onError": "skip" }
// No produces/consumes; multiple contributions into the same agent render as ordered
// labeled blocks (<contribution from="<id>">…) by capability-id (ADR-857 decision 6).
// Gate — checks and optionally blocks
{ "point": "execute:wave:post",
"check": { "query": "ui.safety-gate" }, // {query:…} | {predicate:…} | {agentVerdict:…}
"when": "workflow.ui_safety_gate", "blocking": true, "onError": "halt" }
```
**Hook activation (`when`).** A hook may declare a cheap, **deterministic `when`** over config keys + capability-enablement (e.g. `"workflow.ui_phase"`); `loop.render-hooks` evaluates it to decide whether the hook is active. **Deeper context applicability** ("is this actually a frontend phase?", "are ORM files in scope?") is *not* declared — it stays inside the dispatched skill/agent, which no-ops if inapplicable, exactly where that judgment lives today. This deliberately avoids a phase-context predicate vocabulary that would drift from reality. Consequence: when an entry step self-gates (produces no artifact), its downstream same-capability gate/step must **degrade gracefully** (e.g. `ui.safety-gate` passes when there is no `UI-SPEC.md`) — that is the skill/query's responsibility.
**Gate `check`** is one of:
- `{ query: "<gsd_run query>" }` — deterministic first-party code; **may block**.
- `{ predicate: { kind: "artifact-exists" | "config-equals" | …, … } }` — declarative, no code; **may block**.
- `{ agentVerdict: { ref, prompt } }` — LLM check; **forced `blocking: false` (advisory)** — non-deterministic checks may not halt the loop.
**`role: "runtime"` body** (ADR-857 decision 8 — closed primitive vocabulary; no skills/steps/etc.):
| Field | Notes |
|---|---|
| `runtime.configHome` | config dir |
| `runtime.configFormat` | `settings-json \| toml \| markdown \| markdown-dir \| none` |
| `runtime.artifactLayout` | `{kind, destSubpath, prefix}[]` |
| `runtime.commandStyle` / `hooksSurface` / `sandboxTier` | closed enums (exact sets enumerated in phase 5) |
| `runtime.supportTier` | `1` (Claude/Codex/Antigravity) \| `2` |
### 3. The Loop Host Contract — generated from the workflows
Capability hooks attach to the host, so the host must publish what it exposes (points, agent roles, core artifacts) — otherwise `into: "planner"`, `consumes: ["RESEARCH.md"]`, and `point: "plan:pre"` are unverifiable strings.
**The contract is generated from the workflows, not hand-authored** — so it cannot drift into a lie. The five step workflows carry structured markers; a parser generates the contract from them:
```html
<!-- in gsd-core/workflows/plan-phase.md -->
<loop-point id="plan:pre"/>
<agent-role name="planner"/> <agent-role name="researcher"/> <agent-role name="checker"/>
<loop-artifact produces="PLAN.md" consumes="CONTEXT.md"/>
```
→ generated host contract entry:
```jsonc
{ "step": "plan", "points": ["plan:pre","plan:post"],
"agentRoles": ["researcher","planner","checker"],
"coreArtifacts": { "produces": ["PLAN.md"], "consumes": ["CONTEXT.md"] } }
```
The 12 points (illustrative roles): discuss `pre`/`post` (orchestrator); plan `pre`/`post` (`researcher`/`planner`/`checker`); execute `pre`/`wave:pre`/`wave:post`/`post` (`executor`/`verifier`); verify `pre`/`post` (orchestrator); ship `pre`/`post` (orchestrator).
**Generator validation against the (generated) contract:** every hook `point` ∈ host points; every `contribution.into` ∈ that step's `agentRoles`; every `step.consumes` is satisfiable by `coreArtifacts.produces` or an earlier hook's `produces`; `when` references valid config keys.
### 4. The generators
Two generated artifacts, both following `gen-inventory-manifest`'s `--write`/`--check` + build-wiring + CI drift-test pattern:
1. **`gen-loop-host-contract.cjs`** — parses the workflow markers (§3) → the host contract.
2. **`gen-capability-registry.cjs`** — reads every `capabilities/*/capability.json`, validates each against the JSON-schema (§2), then enforces cross-capability invariants (fail build on violation):
- one owner per skill/agent stem;
- `requires` exist, acyclic, **tier-monotone**;
- hooks valid against the host contract (§3);
- config-key ownership **exclusive AND complete** — a federated key must be owned by exactly one capability *and absent from the central `config-schema`* (presence in both = collision = a mid-flight migration; finish the move);
- emits the registry (§5).
**`tier` is the source of profile/cluster membership.** Install profiles (`core`/`standard`/`full`) and surface clusters are **generated** from capability `tier` + the requires-closure — collapsing ADR-857's dual/triple toggle systems. `/gsd:surface` will operate on capabilities. (This generation lands in the phase-4 install integration; ADR-894 fixes the contract.)
### 5. The generated registry shape
One `capability-registry.cjs`, **role-partitioned indexes**; per-point hook ordering **materialized** (the generator owns ordering; `loop.render-hooks` owns runtime *activation filtering*):
```js
module.exports = {
version: '<schema-version>',
capabilities: { '<id>': {…validated…}, … }, // all roles, by id
bySkill: {…}, byAgent: {…}, // feature-role
byLoopPoint: { 'plan:pre': { // ordering materialized
steps:[…produces/consumes topo-sorted, cap-id tiebreak…],
contributions:[…grouped by into, cap-id order…],
gates:[…as declared…] }, … },
configKeys: { '<key>': '<id>', … },
runtimes: { '<id>': {…descriptor…}, … }, // runtime-role
requiresClosure(id) {…},
};
```
At a point, `loop.render-hooks` reads the materialized order, **filters to the active set** (`when` + enablement), and renders the concrete markdown the orchestrator executes (ADR-857 decision 5).
### Rollout & migration (how this avoids double-execution)
3a-impl builds the registry + host-contract artifacts and the generators **without wiring them into the live loop**. The loop keeps running its currently-inlined features. Each feature's **cutover is one atomic PR** (phase 6) that simultaneously *removes the inlined workflow call* and *activates the capability's hook* — so a feature is never both inlined and hook-fired. No double-run; the registry simply exists, validated, until each feature flips.
### Worked example — the UI capability
```json
{
"id": "ui", "role": "feature", "title": "UI design contracts",
"description": "UI-SPEC design contract + retrospective UI audit for frontend phases.",
"tier": "standard", "requires": [],
"skills": ["ui-phase", "ui-review"],
"agents": ["gsd-ui-checker", "gsd-ui-auditor"],
"hooks": [],
"config": {
"workflow.ui_phase": { "type": "boolean", "default": true, "description": "Enable the UI design-contract gate during planning." },
"workflow.ui_review": { "type": "boolean", "default": true, "description": "Enable the retrospective UI audit." },
"workflow.ui_safety_gate": { "type": "boolean", "default": true, "description": "Block execution on unmet UI-SPEC contracts." }
},
"steps": [
{ "point": "plan:pre", "ref": { "skill": "ui-phase" }, "produces": ["UI-SPEC.md"], "consumes": ["CONTEXT.md"], "when": "workflow.ui_phase", "onError": "skip" },
{ "point": "verify:post", "ref": { "skill": "ui-review" }, "produces": ["UI-REVIEW.md"], "consumes": ["UI-SPEC.md"], "when": "workflow.ui_review", "onError": "skip" }
],
"contributions": [],
"gates": [
{ "point": "execute:wave:post", "check": { "query": "ui.safety-gate" }, "when": "workflow.ui_safety_gate", "blocking": true, "onError": "halt" }
]
}
```
`when` gates each hook on its config key (cheap/deterministic); whether the phase is *actually* frontend work is decided inside `ui-phase` (self-gate). The `plan:pre` step self-skips on a non-frontend phase, producing no `UI-SPEC.md`; the `execute:wave:post` gate's `ui.safety-gate` query passes gracefully when no `UI-SPEC.md` exists. (A `contribution` looks like security's: `{ "point":"plan:pre", "into":"planner", "fragment":{"path":"loop/threat-model.md"}, "when":"workflow.security_enforcement" }`.)
## Grilling amendments
This ADR was stress-tested in two rounds before merge; the format changed materially.
**Round 1 (format):** `loopHooks[]` → three typed arrays (`steps`/`contributions`/`gates`); `contribution.into: <agent-role>`; the Loop Host Contract added; `requires` = capabilities-only + tier-monotone; config federation = atomic move; one registry with role-partitioned indexes.
**Round 2 (operational reality):**
1. **Host contract is generated from workflow markers** (§3), not hand-authored — it can't drift.
2. **Staged cutover** — registry-only until atomic per-feature cutover; no double-run.
3. **`tier` is the source** of profile/cluster membership; profiles + clusters generated; `/gsd:surface` operates on capabilities.
4. **Gate `check`** = query / declarative-predicate / agentVerdict; agentVerdict forced advisory; only deterministic checks may block.
5. **Hook activation `when`** — declarative config-level gating; deeper context applicability self-gates in the skill (no phase-context vocabulary).
6. **`byLoopPoint` ordering materialized** in the registry; resolver filters active + renders. Same-capability hooks must degrade gracefully when an entry step self-gates.
## Consequences
**Positive**
- The format is *enforceable*: hooks validate against a **generated** host contract (no drift), `requires`/`tier`/config invariants are machine-checked, and ordering is materialized + testable.
- `tier`-as-source collapses ADR-857's multiple toggle systems into one generated truth.
- Staged cutover means the whole machinery can land and be validated with zero risk to the live loop until each feature deliberately flips.
**Negative / costs**
- Two new generated artifacts (registry + host contract) and workflow markup to author and keep building.
- The 12 points + agent-role vocabularies + schema are a stability contract — additive-only.
- Config-key migration is atomic-per-feature by design (a half-migrated key fails the gate).
## Alternatives considered
| Decision | Rejected | Why |
|---|---|---|
| Hook shape | one polymorphic `loopHooks[]` | typed arrays let generator/resolver branch on a known shape |
| Contribution target | "inject into the step" | ambiguous for multi-agent steps; `into: <role>` is precise |
| `requires` | capabilities + host steps | host always present → trivially satisfied; capability-only keeps the graph meaningful |
| Registry | two registries / flat map | role-partitioned indexes in one artifact: one generator, role-correct surfaces |
| Config | both-allowed / central-until-cutover | atomic move keeps one source of truth |
| Host contract | hand-authored + drift test / runtime-assert | generate-from-workflows makes drift impossible by construction |
| Profiles | profiles authoritative / tier-default-with-overrides | `tier`-as-source is the ADR-857 unification goal |
| Gate checks | query-only / agentVerdict-blockable | predicates avoid trivial code; non-deterministic blocking gates flap |
| Activation | full `when` over phase context / enablement-only | config-level `when` is cheap+honest; phase context self-gates (no drift-prone vocab) |
| Migration | big-bang / source-flag | atomic per-feature cutover: safe, staged, no coexistence flag to retire |
## Open questions (genuinely deferred to build sub-phases — cheap to decide then)
- JSON-schema `$id`/versioning; where `capability.schema.json`, the workflow markers' schema, and the generated host-contract file live.
- The declarative-predicate vocabulary for gates (`artifact-exists`, `config-equals`, …).
- The exact `commandStyle`/`sandboxTier`/`hooksSurface` enums for `role: runtime` (phase 5, against the 15 runtimes).
- Point/role-set deprecation policy once third-party capabilities exist (additive-only holds until then; a rename/removal needs a major bump + deprecation window — deferred with third-party loading per ADR-857).