Skip to content

docs: propose local skill source governance - #30574

Closed
hkrishg-aws wants to merge 1 commit into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc-clean
Closed

hkrishg-aws wants to merge 1 commit into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc-clean

Conversation

@hkrishg-aws

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the governance design for letting an operator's policy narrow which repository and config-selected local directories may supply skills to an agent.

A project's .kiro/skills, skills.extra_paths, local skill:// mappings and the KIROCREW_PROJECT_DIR source can supply SKILL.md instructions, but no policy key represents those source roots today. Project skills have a local off switch and directory trust grant; neither gives an enterprise operator a central ceiling.

Why it matters

A repository or local configuration can select skill content that enters the agent's context. The operator can govern discovery registries and many tool effects, but cannot centrally restrict these source directories. The design adds that missing ceiling without turning policy approval into a project trust grant.

Not a goal

  • Implementing the policy key or changing runtime behavior in this PR.
  • Governing the user's global skill roots, where packaged, installed and manually authored content share one path.
  • Governing skill content integrity, signatures or digests after a source is admitted.
  • Resolving remote or container path identity before a maintainer chooses the namespace.
  • Changing project-skill trust or enabling project skills on unsupported platforms.

What changed (motivation → approach → change)

This docs-only PR adds rfc-local-skill-sources-governance.md. It proposes an allow-only skills.local_sources policy key over canonical source roots, with policy acting as a conjunct beside the existing local controls. Four maintainer decisions are called out at the top.

The rollout has two gates. Phase 0 inventories detected roots and previews the policy decision without changing admission. Phase 1 enforces the enterprise default-off behavior only after that preview exists. The RFC defines 22 executable Phase 1 assertions, including profile handling, path aliases, source replacement, catalog-generation races, duplicate-name shadowing, audit deduplication and harness parity.

The accepted enterprise-edition RFC's single "Extension sources" row is split into registry hosts and local skill sources, raising the appendix count from 66 to 67. The request-for-change index gains the new draft row.

Backwards compatibility

Compatible: this PR changes documentation only. The RFC records that its future Phase 1 would be a breaking enterprise default, preceded by a non-enforcing Phase 0 preview and migration recipe.

Removes nothing: no runtime, policy parser, skill source, configuration or user-facing behavior changes in this PR.

Tests

Proof: not provable -- docs-only change.

  • make build passed.
  • ./scripts/docs-lint.sh passed.
  • .venv/bin/python scripts/local-gate.py passed: 505 backend tests and 13,395 frontend tests.

Manual verification

Reviewed all three changed documents against upstream main and confirmed the RFC index, enterprise control counts and cross-links agree. Confirmed no customer, private security-report or internal-only content appears in the diff.

Screenshots / video

N/A, docs-only design proposal with no user-interface change.

Related Issues

Refs #29686

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing change-scoped tests pass
  • Self-review completed; documentation follows repository conventions
  • Documentation and indexes updated
  • No secrets, credentials or internal references in the diff

Contribution License Agreement

Contributed under the repository's Apache-2.0 license.

Define an allow-only policy ceiling for repository and config-selected skill sources. Add a pre-enforcement inventory phase and align the enterprise control table.

Refs: kirodotdev#29686
@github-actions github-actions Bot added the fork Pull request from a fork (external contributor) label Nov 5, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 5, 2026
@hkrishg-aws

Copy link
Copy Markdown
Contributor Author

Closing in favour of #34728, which carries the same design and merges cleanly.

This branch cannot merge. It edits docs/request-for-change/rfc-crew-enterprise-edition.md, and #32970 renamed that file to rfc-crew-lts-edition.md on 2026-11-08, three days after this branch was filed. Git therefore sees modify-versus-delete rather than a content conflict, which is why the state is dirty rather than something a rebase alone would settle.

#34728 is the same RFC as one commit on current main, retargeted to the LTS file. Three things changed in the move, all recorded there:

  • The appendix row split now reads against rfc-crew-lts-edition.md, and the local-sources row links to the RFC.
  • The Yellow class count moved from 20 to 17 on main while this branch sat, so splitting one row into two yields 18, not the 21 this branch proposed. The appendix heading ### Yellow (n) is updated alongside the class-table cell, which this branch missed.
  • The control count goes 66 to 67 in both places it appears, not just one.

The proposed key skills.local_sources and the policy term crew_extension_local_sources are unchanged, since the appendix kept its crew_extension_* naming through the rename.

Tracking issue #29686 is unaffected.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 10, 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.

1 participant