Skip to content

docs: propose local skill source governance - #30563

Closed
hkrishg-aws wants to merge 2 commits into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc
Closed

hkrishg-aws wants to merge 2 commits into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc

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,381 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 fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Nov 5, 2026
Preserve the latest D7 amendment while splitting extension sources into registry and local-skill controls.

Refs: kirodotdev#29686
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 5, 2026
@hkrishg-aws

Copy link
Copy Markdown
Contributor Author

Superseded by #30574. The first draft branch was created before upstream amended the same enterprise RFC and could not merge cleanly. #30574 carries the same design as one commit on current main.

@hkrishg-aws hkrishg-aws closed this Nov 5, 2026
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 5, 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