golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
f72f70ad3985d7ffd28fefd86a8f9ca9b6f0d5ac
msd-core/docs/README.md
Tom Boucher f72f70ad39 docs(#2782): how-to for declaring a reviewer lane in a capability (#2906) 
* docs(#2782): how-to for declaring a reviewer lane in a capability

ADR-2782 shipped the Reviewer Lane capability surface in 1.9.0, but the
only documentation was reference (capability-manifest.md) and rationale
(ADR-2782). A capability author had no task-oriented path from "I have a
review CLI" to "/gsd:review invokes it".

Adds docs/how-to/ship-a-reviewer-lane.md: role selection, the spawn and
openai-http worked examples, federated config ownership, the
review-lane query surface as the verification step, what the install
disclosure and egress-host re-verification mean for the author, and the
data-only boundary with the two named CLIs that do not fit today.

Also corrects the manifest reference's `invoke` row, which understated
three enums against the shipped validator: promptChannel omitted `argv`,
effortChannel omitted `env`, and the openai-http sub-shape plus the
required-with-file-arg `outputArg` were undocumented entirely.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2782): correct four claims found by the two orthogonal reviews

Security review (1 major, 2 minor):
- "a reserved slug" implied the gsd-/anthropic- namespace rule, which
  guards the capability id, not reviewer.slug. The slug guard is
  isReservedName (__proto__/constructor/prototype), a prototype-pollution
  barrier. Both rules are now stated and kept apart.
- Added ADR-2782 D5's own caveat verbatim: disclosure and host pinning
  make the channel visible, pinned and revocable, not safe, and
  consent-at-install is a weaker gate for a standing egress channel than
  for a hook.
- Named integrity/SHA pinning and engines.gsd as the controls that make
  the disclosure tamper-evident and the version range enforceable.

Correctness review (1 major, 1 minor):
- Claimed a name collision is "a hard failure at install". It is not.
  installCapability never runs validateCrossCapability; the check runs in
  loadRegistry, and a colliding overlay is dropped from acceptedMap with a
  warning while the install reports success. Documented as the quiet
  failure mode it is, with the symptom to look for.
- The feature-only field list omitted hooks and activationKey, both of
  which FEATURE_FIELDS_FORBIDDEN_ON_REVIEWER rejects.

Both worked examples re-validated against validateCapability() -> [].

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2782): restore Kimi Code to the cross-AI reviewer list

set-up-cross-ai-review.md named eleven reviewers; twelve lanes ship. The
kimi-code lane (added by #2718, declared as manifest data by #2798) was
never added here — the same roster-drift class as #2781, which #2800's
parity gate covers for COMMANDS.md and FEATURES.md but not for how-to
prose.

Also points readers at the declared-lane model rather than a static list:
the roster is now generated, a capability can ship its own lane, and
`gsd-tools review-lane sections` answers "what do I actually have".

Verified against the twelve declared bodies in capabilities/*/capability.json.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2782): use the invocation form the runtime descriptors actually declare

The new guide used /gsd:review. Nothing in this repo produces that form.

- capability-validator VALID_COMMAND_STYLES is {slash-hyphen, shell-var};
  there is no colon/namespaced style in the vocabulary at all.
- 18 of 19 runtime capabilities declare commandStyle "slash-hyphen",
  claude included; codex is "shell-var". Every artifactLayout prefix is
  "gsd-".
- A plain-file command install never namespaces, so .claude/commands/
  gsd-review.md is typed /gsd-review.
- The Claude Code plugin surface would namespace on plugin.json "name",
  which is "gsd-core" -- so the plugin form would be /gsd-core:review.
  The commands/gsd/ subdirectory is cosmetic and contributes nothing to
  the invoked name.

So /gsd:review is neither the installed form nor the plugin form. Uses
/gsd-review, matching set-up-cross-ai-review.md and the 18 descriptors.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2782): state that lane listing is not wired yet

The guide could describe authoring, validating, and installing a lane but
implied a publishing path that does not exist. Neither discoverability
catalog can accept one: a Community Capability Registry entry requires a
non-empty loopExtensionPoints plus hookKinds, and a role:"reviewer"
capability is forbidden from declaring steps/contributions/gates, so both
fields are unsatisfiable rather than merely unset. The EoS Registry is
ADR-1239 host integrations, which a lane is not.

The registry schema predates the reviewer role by 17 days (#2182 Jul 11,
ADR-2782 Jul 28) and registry-schema.cjs has zero occurrences of
"reviewer". Tracked for a 1.9.x point release by #2904.

Says so explicitly, and tells authors NOT to file a loop extension point
they do not use to get past validation -- a schema satisfiable only by
lying is one that will be lied to.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* chore(#2782): backfill PR number and fix the changeset invocation form

pr: 0 -> 2906.

Also corrects /gsd:review -> /gsd-review in the fragment body. The
fragment renders into CHANGELOG.md, which is a reader-facing docs surface
and is never passed through the install-time converter -- so the colon
form would ship the #2903 drift into a permanent release artifact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(#2907): propagate the invocation-form fix and restore lane order

Two findings from an isolated review of the post-review delta.

- docs/README.md and develop-a-capability.md still said /gsd:review in
  the cross-links added for the new guide. The form was corrected in the
  guide itself but not in the two entries pointing at it, leaving three
  docs making the same claim in two different forms.
- set-up-cross-ai-review.md inserted Kimi Code between Antigravity and
  Ollama. REVIEWER_LANES is ordered by write_reviews order and kimi-code
  is 12th, appended after llama_cpp; the prose list mirrored declaration
  order before this change and now does again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Test <test@example.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit 557d46984e)
2026-07-31 08:19:59 -04:00

7.9 KiB
Raw Blame History

GSD Core documentation

Documentation is organised into four quadrants: tutorials help you learn by doing, how-to guides solve specific tasks, reference states authoritative facts, and explanation explores concepts and design decisions.

Language versions: English · Português (pt-BR) · 日本語 · 简体中文

Tutorials

How-to guides

Reference

Explanation

Related

Reference in New Issue View Git Blame Copy Permalink