Skip to content

docs(rfc): propose discovery-registry governance - #16007

Closed
hkrishg-aws wants to merge 2 commits into
kirodotdev:mainfrom
hkrishg-aws:docs/rfc-discovery-registry
Closed

hkrishg-aws wants to merge 2 commits into
kirodotdev:mainfrom
hkrishg-aws:docs/rfc-discovery-registry

Conversation

@hkrishg-aws

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the proposal and request a maintainer decision on whether an
operator can restrict external discovery registries through the public
governance ceiling rather than an edition adapter.

The public default registry policy admits every registry
(DefaultExternalAccessPolicy.admits_registry in src/kiro_crew/platform/defaults.py),
and the built-in catalog has no discovery-registry scope (SCOPE_CATALOG in
src/kiro_crew/platform/governance.py).
Repository evidence is measured at the RFC's audited-at revision.

Why it matters

An operator cannot express this admission restriction in the existing public
security-policy document. The edition seam can express it today
(ExternalAccessPolicy in src/kiro_crew/platform/interfaces.py); the RFC asks whether that boundary
is intentional, and records the shared-catalog and restart costs of changing it.

Not a goal

  • Implementing a scope or changing runtime behavior.
  • Fixing host-pattern validation, invalidating catalogs, or adding per-kind rows.
  • Governing all egress, manual/local installs, or MCP tool execution.

What changed (motivation → approach → change)

  • Add docs/request-for-change/rfc-discovery-registry-governance.md, status draft.
  • Add its RFC index row, verified against main rather than describing proposed
    behavior as shipped.
  • Record one host-keyed row, _url_host(api_base) extraction, the shared admission
    gate with tightest-wins, explicit no-external-registry-floor semantics, and a
    next-start guarantee with the lazy-first-use qualification.
  • Ask one decision: public ceiling or edition-only. Landing a draft does not
    record acceptance (the "Status vocabulary" section of docs/request-for-change/README.md).

Backwards compatibility

Compatible: documentation only. No code, configuration defaults, or runtime
permissions change.

Tests

No runtime tests added, documentation only. python3 scripts/docs_lint.py passes
on main with both files in place, and the repository's PR-description checker passes.

Manual verification

The RFC's code references, four external admission call sites, lazy caches,
matcher behavior, and agent_backend semantics/timing were checked against
local main at the RFC's audited-at revision. No gateway behavior or live CI was exercised.

Related Issues

Refs #12677

  • #12677: proposed scope and
    narrowed design.
  • #13966: separate host-pattern
    validation defect. Its #14004
    work is not changed or duplicated here.

Checklist

  • At most two commits, one preferred, with a Conventional Commits title.
  • Required checks pass; no new runtime functionality to test.
  • Author self-review completed against the cited baseline.
  • RFC and directory index added together; docs lint passes.
  • No secrets, credentials, or internal references in the diff.

Contribution License Agreement

@hkrishg-aws
hkrishg-aws requested a review from a team as a code owner October 1, 2026 21:11
@hkrishg-aws
hkrishg-aws requested a review from kyleseaman October 1, 2026 21:11
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 3c8c679f3b79cb89af01488a0e17d988c106559d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3c8c679

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 3c8c679f3b79cb89af01488a0e17d988c106559d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the README's provenance paragraph gets an "added … verified against 0d0b4598d" sentence for this row, as every other row has.

[DESIGN-REVIEWED] 3c8c679

Description read

[DESCRIPTION-READ] 0525a016ee9d9a4b0c070532e93466708e985c4b89977515b911f2667f05d5ef

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 3c8c679f3b79cb89af01488a0e17d988c106559d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 3c8c679

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 2, 2026
@hkrishg-aws
hkrishg-aws force-pushed the docs/rfc-discovery-registry branch from 797174d to f1aeb23 Compare October 2, 2026 14:33
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 2, 2026
@hkrishg-aws
hkrishg-aws force-pushed the docs/rfc-discovery-registry branch from f1aeb23 to e57d0a6 Compare October 2, 2026 15:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026
@bolichen97
bolichen97 force-pushed the docs/rfc-discovery-registry branch from e57d0a6 to 551f60b Compare October 6, 2026 09:47

Copy link
Copy Markdown
Contributor

Rebased onto current main (cc7e79894e) since this branch had no activity for more than 6 hours.

  • Old head: e57d0a640e → new head: 551f60bc8d
  • No conflicts. The range-diff shows docs(rfc): record the doc PR number is identical. In docs(rfc): propose discovery-registry governance, only the README context lines around the new row changed, because rows were added on main. The added rfc-discovery-registry-governance row and the new RFC file are unchanged.
  • Checks: this PR has no Python changes. The docs and RFC-index-related tests pass (934 passed). The 2 failures in test_pipeline_conductor_skill_contract.py also fail on main and are not caused by this PR.

Pushed with --force-with-lease against the previous head. Please re-pull before making further changes.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 6, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Reviewed, not approving (crew-pr-reviewer). This is a governance RFC. Merging it reads as accepting the policy, which is a maintainer decision.

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 3c8c679f3b79cb89af01488a0e17d988c106559d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 19, 2026
@iamwhatever
iamwhatever force-pushed the docs/rfc-discovery-registry branch from 548f333 to de8980d Compare October 20, 2026 00:43
@iamwhatever

Copy link
Copy Markdown
Contributor

Rebased again: main added another RFC index row and the README conflicted. New head de8980d8a3 on aa71296bd. Same resolution (all main rows kept, this RFC's row first); RFC file and commit 2 unchanged. The previous head's CI was fully green after one rerun of an unrelated flaky test (test_config_loader_default_agent.py::TestDanglingDefaultAgentReset, RecursionError in PosixPath). docs_lint passes locally.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 20, 2026
Record a draft RFC asking whether external discovery-registry admission
belongs in the public governance ceiling or stays edition-only, and add
its row to the RFC index. Documentation only.

Refs kirodotdev#12677
@iamwhatever
iamwhatever force-pushed the docs/rfc-discovery-registry branch from de8980d to 3c8c679 Compare October 20, 2026 02:27
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 20, 2026

@dodgeblaster dodgeblaster left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stewarding review (sweep triage) — RFC fits the data model; the one open question is correctly a maintainer call.

I verified the RFC's premises and its proposed shape against current main (41987ae89b). The doc is accurate and the proposed design is consistent with the governance data model and the repo's own invariants. Scoped notes below, then the two things that keep this review at request-changes rather than approve.

The premises hold on main

  • No discovery-registry row exists in the catalog — SCOPE_CATALOG now lives in src/kiro_crew/platform/governance_parts/catalog.py, and registries is absent (the host-matched rulesets are network.egress at catalog.py:127).
  • DefaultExternalAccessPolicy.admits_registry still returns True unconditionally (src/kiro_crew/platform/defaults.py:459-460), so the public build cannot narrow registry admission from security_policy.json today. The premise is intact.

The proposed shape fits the model and the invariants

  • It is a pure data-row add: ScopeSpec(RULESET, matcher="host"), reusing the existing host matcher (_match_host / _MATCHERS in src/kiro_crew/platform/governance_parts/matching.py:98,129) and _url_host extraction (matching.py:193). No new matcher, no evaluator edit — consistent with AGENTS.md:128 ("adding a scope is a SCOPE_CATALOG data change, never an evaluator edit") and the append-only nature of register_scope (catalog.py:400).
  • CONTRACT_VERSION stays 1 (src/kiro_crew/platform/context.py:80): adding a catalog row does not change the companion contract, so the RFC's implicit "no bump" is correct.
  • The hostless-input semantics are right: _url_host returns "" for a URL with no network host, and under mode:"allow" an empty string matches only a catch-all like * — the RFC states this.
  • Placing the shared check in _shared.admits_registry (tightest-wins over the edition policy) rather than only in DefaultExternalAccessPolicy is the correct layering, since an edition replaces the external_access slot wholesale (src/kiro_crew/platform/context.py). The RFC calls this out.
  • The next-gateway-start timing choice (lazy per-process catalog caches, no live invalidation) mirrors the agent_backend restart contract rather than inventing live revocation. Reasonable and documented.

Why request-changes, not approve

  1. Merge state. The PR is CONFLICTING and ~104 commits behind main; only the fork author (hkrishg-aws) can rebase and resolve. As a fork PR this is review-only on our side — we neither push to the branch nor merge it.
  2. It is a draft-status RFC with a live open question. By the RFC's own exit criterion ("acceptance is explicit, not inferred from merge"), it should not be approved-to-merge while the single governance decision is unanswered: does external discovery-registry admission belong in the public governance ceiling (one host-keyed registries row), or should it stay edition-only? That is a security-policy product decision for the maintainers — it changes what operators of the public build can allow/deny. Nothing in the code settles it; recording it under docs/decisions/ (or accepting the RFC non-draft) is the gate.

No code defects to fix in the doc itself. This stays open pending the maintainer's ceiling-vs-edition ruling and the author's rebase.

@dodgeblaster

Copy link
Copy Markdown
Contributor

For information, not a ruling on this RFC: the open question here (public governance policy vs edition-only) is covered by the accepted enterprise-edition RFC, which lists "Extension sources" as the governed key external_access.registry_hosts, off by default in the enterprise edition (docs/request-for-change/rfc-crew-enterprise-edition.md, appendix).

An implementation is up as draft #28530. It follows the design agreed in #12677's comments: one host-matched key judged on the host of api_base, checked in the shared admits_registry gate so the stricter of policy and edition wins, unchanged when unset on a regular install, and binding at the next gateway start.

Thank you @hkrishg-aws for the design work here and in #12677, and for the offer to write it. Review on #28530 is very welcome.

@hkrishg-aws

Copy link
Copy Markdown
Contributor Author

Closing this RFC as superseded by #28530.

The gap this RFC raised. The public build had no governance key for the skill and MCP discovery registries. DefaultExternalAccessPolicy.admits_registry returned True unconditionally (src/kiro_crew/platform/defaults.py:459-460), and SCOPE_CATALOG had no row for registries. A security_policy.json naming one was refused whole as an unknown governed key. In practice:

  • Every install queried skills.sh, the GitHub API and the official MCP registry from the Discover surfaces (Add Skill, Add MCP Server) and from the agent's skill_discover, and an operator had no way to narrow that.
  • An enterprise build did the same, although the accepted enterprise-edition RFC lists this control ("Extension sources") as off by default.
  • capabilities.extension_install already governs installing. Discovery is the step before it: which public catalogs developer machines and agents reach out to, and what gets surfaced to them as installable. An organisation that must limit where skills and MCP servers come from could govern the install but not the browsing, so its egress and supply-chain boundary had a hole at the discovery step.

How #28530 closes it. The policy question this RFC left open (public governance ceiling or edition-only) is settled by the enterprise-edition RFC appendix. #28530 implements the design agreed in #12677:

  • A new host-matched key, external_access.registry_hosts, judged on the host of each provider's api_base, never its self-chosen name. A provider that repoints at another host stops being admitted.
  • The key is checked in the shared admits_registry gate that all four registry call sites go through, before the edition's policy. The stricter answer wins, so an edition can't loosen what the operator's policy refuses.
  • It fails closed on an evaluation error, and governed decisions are audited.
  • On a regular install nothing changes until a policy names the key. In an enterprise build the baseline is off, so no registry is queried until the policy lists its hosts.
  • A policy change binds at the next gateway start, matching the agent_backend restart contract.

Thanks @dodgeblaster for taking the design from #12677 and this RFC into the implementation. I've reviewed and approved #28530, with one non-blocking suggestion (url_policy_hosts for the host reading) and an offer to write operator docs as a follow-up. #12677 stays open until #28530 merges, since that PR closes it.

@hkrishg-aws hkrishg-aws closed this Nov 3, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants