Skip to content

docs(rfc): Projects revision 2 -- the thin Project - #11564

Merged
bolichen97 merged 1 commit into
mainfrom
docs/rfc-projects-thin
Sep 18, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/rfc-projects-thin

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

The Projects RFC on main describes a bundle that installs its own agents, skills and MCP servers into the install's global state at activation. Building that (PR #7181) took twelve review rounds, and almost every blocker was the same class: a privileged reader trusting state an agent shell can write. Meanwhile main grew the same capability by a different route: a session's project directory already discovers its own .kiro/skills, project-local agents and .kiro/steering, and kiro-cli reads a workspace-level .kiro/settings/mcp.json on its own. The RFC no longer says what the design should be.

Why it matters

Without a recorded decision, the implementation keeps paying for a layer the runtime already provides, every new head re-opens the same security class, and the two things only a runtime can give a Project (a memory store keyed to it, and MCP servers it can name) have no design at all. A First Principles lane also needs a non-draft RFC on main before a product-shape PR can land.

What changed (motivation → approach → change)

A Project gets smaller and keeps only what needs a runtime. The RFC in docs/request-for-change/rfc-crew-projects.md gains a Revision 2 section, placed after the TL;DR, that supersedes the capabilities half of the original design and leaves the sources, sessions and sharing design standing.

Part of a Project Before After
Registry, activation record under trust/ (sandbox-visible) 🟨 a gateway-only leaf on both fences (_SENSITIVE_HOME_DIRS and _CREW_HIDDEN_LEAVES)
Synced Git workspace kept 🟦 kept, coordinates pinned in the registry
Agents, skills, steering 🟥 installed from the bundle at activation reach the session through cwd discovery, which main already does
MCP servers 🟥 definitions copied into global mcp.json 🟩 referenced by name, resolved onto the session agent from the owner's catalogue
The checkout's own .kiro/ directory unaddressed 🟩 everything under it except .kiro/steering/ is in the activation digest; a sync that changes it marks the Project review stale and sessions refuse until the owner re-activates against the digest of the content shown
Manifest identity id present, unexplained 🟨 id kept as the structural identity the store keys on (name is for people), adopted before manifests circulate
Memory none 🟩 memory.mode: project — declared in the manifest, ratified at activation, a Memory V2 store owned by a project--<id> member
Providers, knowledge recipes, CLI P1/P2 🟦 deferred, list shape kept

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

The manifest declares whether a Project has memory, never which store, so a bundle can never point a session at someone's private memory. A pull can never create or select a store either: activation is the owner's one trust step, and a manifest edit makes the activation stale until the owner re-activates. The same rule governs MCP: a repo names servers, the owner's install supplies the definitions, and an unknown name shows as unavailable. The checkout is treated as a second channel and decided rather than assumed: everything under its .kiro/ directory except .kiro/steering/ is inside the activation digest (default-stale, so a discovery surface kiro-cli adds later is covered without Crew knowing its name), a synced commit that changes it stops sessions until the owner re-activates, and text surfaces (.kiro/steering, documents) inherit kiro-cli's existing repository-trust posture. The storage rule is spelled out with the two fence tables it must sit on, and the revised migration plan names three PRs (thin Project, memory.mode, MCP by name) with exit criteria. The original agent-context section is marked superseded, the front matter is re-audited at 0640c1e0d5, and the index row in docs/request-for-change/README.md says what exists on main today.

Tests

N/A — documentation only. scripts/docs_lint.py, docs-lint.sh, the comment-history, brand, feature-map and changelog gates all pass on this diff.

Manual verification

Two claims in the text were checked against sources rather than memory: the kiro.dev MCP configuration page for the workspace-level .kiro/settings/mcp.json precedence, and src/kiro_crew/sandbox.py for trust being in _CREW_SANDBOX_VISIBLE_LEAVES while memory_stores is in _CREW_HIDDEN_LEAVES.

Related Issues

Related: #3551 (Projects tracking issue). Supersedes the design carried by PR #7181, which will be split per this revision.

no linked issue: a design revision, it closes nothing.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@kyleseaman
kyleseaman requested review from a team and chenmingwei23 September 17, 2026 18:32
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Intent: Record the maintainer's decision to narrow Projects to the parts only a runtime can provide -- a fenced registry, a synced Git workspace, a memory store keyed to the Project, and MCP servers referenced by name -- so the implementation can be split into small PRs against a design that is written down.
Not a goal: Changing any code or behaviour; deciding the deferred phases (providers, knowledge recipes, S3, CLI); resolving the three new open questions.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed f95df9e101ff9f30326f5356ffdacee58798f5c7 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] f95df9e

Verdict parsed from the review's SHA-scoped output markers for commit f95df9e101ff9f30326f5356ffdacee58798f5c7.

False positive or not applicable? A repository writer can comment:
/ai-review override fable f95df9e101ff9f30326f5356ffdacee58798f5c7: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of f95df9e101ff9f30326f5356ffdacee58798f5c7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f95df9e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f95df9e101ff9f30326f5356ffdacee58798f5c7: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of f95df9e101ff9f30326f5356ffdacee58798f5c7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Motivation cites needing a non-draft RFC on main, yet front matter stays status: draft — confirm ratification is a deliberate separate step.

[DESIGN-REVIEWED] f95df9e

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 17, 2026
@kyleseaman kyleseaman mentioned this pull request Sep 17, 2026
5 tasks done
@kyleseaman
kyleseaman force-pushed the docs/rfc-projects-thin branch from a5a3fbb to 1d9c937 Compare September 17, 2026 21:31
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Synced checkout is a second MCP channel outside the activation digest (span=d9915bfbc5b4) -- fixed in 1d9c937

The Watch item is right: the "never introduces an executable" claim held only for Crew's by-name resolution path, while sync pulls remote commits and kiro-cli reads the checkout's own .kiro/settings/mcp.json and .kiro/agents/ at the next session start.
Revision 2 now scopes the by-name claim to Crew's path and DECIDES the seam in a new section, "The synced checkout is a second channel": the activation digest covers the primary checkout's .kiro/settings/mcp.json and .kiro/agents/; sync recomputes it and a moved digest marks the Project review stale; session start and per-turn re-resolve refuse with project_review_stale until the owner re-activates.
PR A's exit criteria name the seam explicitly (a sync that changes those files must stop the next session start), and former open question 8 is retired as decided.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • State by decision that cwd discovery of steering and project-local agents inherits kiro-cli's repo-trust posture (span=6b2599bcf60a) -- fixed in 1d9c937

Taken, with one split the suggestion did not make: project-local agents can carry mcpServers, so they are an EXECUTABLE surface and go under the activation digest with the workspace MCP file, not under the text posture.
The text surfaces (.kiro/steering, the checkout's documents) now carry the requested sentence: they reach the session as instructions kiro-cli loads from any directory it runs in, a Project checkout is no more and no less trusted than a directory the user opened by hand, and the agent-side defence (injected text is data) is the one every session already relies on. .kiro/skills keeps its existing per-directory consent grant.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Inherited CI reds, not this PR's. The five backend shards that failed on a5a3fbbc5d (Linux 5 and 6, Windows 5 and 7) plus the Coverage Gate that depends on them all fail on the same six tests, and this PR changes two markdown files:

  • test/test_session_control.py::test_private_creator_cannot_change_memory[writer-canonical|public-worker-canonical] and ::test_create_refuses_unreadable_delegation_identity[OSError|ValueError]
  • test/test_member_session_control.py::TestMemberChildPrivateBinding::test_global_caller_cannot_grant_a_child_private_authority and ::test_a_v1_child_writes_no_private_binding

Reproduced on a clean detached origin/main (40624a1fb7, repo venv, Linux): 4 failed, 4 passed and 2 failed, 8 passed with the identical assertions. No commit touching those files has landed on main since this branch's base. I'll rebase the moment a fix lands; nothing in this diff can change the outcome.

@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 Sep 17, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-projects-thin branch from 1d9c937 to 37b4141 Compare September 17, 2026 23:12
@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 Sep 17, 2026
@kyleseaman
kyleseaman force-pushed the docs/rfc-projects-thin branch from 37b4141 to 65f2a0d Compare September 18, 2026 02:05
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 18, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Digest scoped to the primary checkout while the example declares a reference source (span=1f7087c0edba) -- fixed in 65f2a0d

Taken via the second clearing path the item offered: the RFC now states the invariant the runtime already holds -- a Project session's working directory is only ever the primary checkout (the bundle clone when no source is declared primary); reference checkouts are materialized beside it and are never a kiro-cli workspace root, so kiro-cli never reads their .kiro/settings/mcp.json or .kiro/agents/.
PR A's implementation enforces exactly this (describe_project_sources resolves one primary checkout as both the session cwd and the digest root), so the text now matches the code rather than the code being widened.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Fold open question 9 into PR B's exit criteria (span=043770ed5dec) -- fixed in 65f2a0d

Decided as suggested: the store's lifetime is the Project's, never the manifest's -- re-activation keeps the store, and flipping memory.mode back to none leaves it bound until the Project is removed. Written into PR B's description and exit criteria; the open-questions list drops it.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 18, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Digest is an allowlist of kiro-cli discovery surfaces Crew does not control (span=e3101eacf51b) -- fixed in 7cd9294

Taken via the first clearing path: the digest is inverted to default-stale over everything under the primary checkout's .kiro/ directory, with exactly one text-only carve-out (.kiro/steering/) and a guard test pinning the carve-out set. A surface kiro-cli adds later moves the digest and the owner reviews it, instead of slipping through an enumeration.
.kiro/skills is stated as under the digest (a skill can carry scripts) while keeping its consent grant. PR A's exit criteria are updated to the inverted scope; its code currently enumerates the two files and will be widened to the glob before it lands.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Test the primary-checkout cwd invariant instead of assuming it (span=33a8a1c41b03) -- fixed in 7cd9294

Added to PR A's exit criteria: a session cannot be bound to a reference checkout as its working directory (the binding resolves to the primary checkout or refuses), so the digest's scope and the session's cwd are the same tree by construction, and the second-channel section now says the invariant is tested rather than held.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 Sep 18, 2026
Narrow the Projects RFC to the parts only a runtime can provide: a fenced registry, a synced Git workspace, a memory store keyed to the Project (memory.mode), and MCP servers referenced by name. The capabilities layer (installing a bundle's agents, skills and MCP into global state at activation) is superseded by cwd discovery, which main already delivers, and by kiro-cli's own workspace-level mcp.json. Records the revised migration plan (PR A thin Project, PR B memory.mode, PR C MCP by name), the two-fence storage rule, and re-audits the index row.
@kyleseaman
kyleseaman force-pushed the docs/rfc-projects-thin branch from 7cd9294 to f95df9e Compare September 18, 2026 05:18
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Surface the content of changed .kiro/ files at re-activation, not just their names (span=25d84106c59c) -- fixed in f95df9e

The RFC now states re-activation is digest-bound: the review surface shows each changed file's current content (added, changed, removed, or unreadable with the reason) and the accept call carries the digest those bytes hash to; a recompute that differs refuses with project_review_moved and records nothing. PR A's exit criteria name the same rule, and PR #11678 implements it (preview endpoint plus the review dialog in its evidence frames).

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Sep 18, 2026

@bolichen97 bolichen97 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.

Reviewed the full production diff on f95df9e. 将Projects RFC收敛为薄项目模型及分阶段实施计划。

仅RFC正文和索引,完整文本已由只读审查者阅读;不改变运行时代码、权限或存储。未按文档或架构类别人为增加审批门槛;具体讨论未发现有效hold。 本轮已合并项仅为已审查且归档的授权变更;写前逐文件对照证明本项生产文件及文档自阶段A没有变化。

Fresh REST checks: current-head PR Readiness success; no effective change request or unresolved review hold; CODEOWNERS/UX eligibility and the distinct last pusher verified. Optional baseline failures, if present, remain recorded and are not claimed green. This approval does not bypass branch protection.

@bolichen97
bolichen97 merged commit f21d760 into main Sep 18, 2026
86 checks passed
@bolichen97
bolichen97 deleted the docs/rfc-projects-thin branch September 18, 2026 11:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 18, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
Narrow the Projects RFC to the parts only a runtime can provide: a fenced registry, a synced Git workspace, a memory store keyed to the Project (memory.mode), and MCP servers referenced by name. The capabilities layer (installing a bundle's agents, skills and MCP into global state at activation) is superseded by cwd discovery, which main already delivers, and by kiro-cli's own workspace-level mcp.json. Records the revised migration plan (PR A thin Project, PR B memory.mode, PR C MCP by name), the two-fence storage rule, and re-audits the index row.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants