Skip to content

docs(rfc): Projects — identity at registration, keys land with the PR that reads them - #11828

Merged
iamwhatever merged 1 commit into
mainfrom
docs/rfc-projects-registry-id
Sep 18, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
docs/rfc-projects-registry-id

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Revision 2 of the Projects RFC (#11564, merged) sketched a project.yaml carrying three keys nothing in PR A (#11678) reads: a manifest-minted id, mcp[] and memory.mode. The First Principles lane raised the parsed-but-unused keys on three consecutive rounds of PR A, and its retrospective found that the argument the RFC gave for them inverts on inspection: unknown manifest keys are validation errors, so admitting a key later is compatible while retracting a shipped one is breaking. The manifest id had the same shape, justified by the previous attempt's store rather than by any current consumer.

Why it matters

project.yaml is committed into users' repositories and read by every install forever. A key that ships before anything reads it becomes a promise the schema cannot take back; an identity that lives in an agent-writable file is one more thing a privileged reader has to distrust. The maintainer decided both: the keys leave PR A's schema and each arrives with the PR that acts on it, and the Project id is assigned at registration. This PR records that decision where PR A's body points to it.

What changed (motivation → approach → change)

Part What this PR does Where
Manifest sketch 🟨 the PR A schema is apiVersion, kind, name, description, sources; memory.mode and mcp[] are shown separately as arriving with PR B and PR C, with the compatibility rule that puts a key in the schema only when something reads it, and its reader side: an install that has not upgraded refuses a newer manifest by name, upgrade is the remedy, and apiVersion moves only on a retraction or a change of meaning docs/request-for-change/rfc-crew-projects.md § What a Project is, revised
Identity 🟨 the id paragraph is replaced: the registry mints the id at add; every install-local key (managed clone, provenance records, digest, member record, PR B's store) hangs off it; re-adding a registered location returns the existing registration; cross-install sameness is not a PR A property same section; § Memory keyed to the Project
Migration plan 🟨 PR A's schema and two new exit criteria (re-add returns the existing registration; id:/mcp:/memory: refused by name); PR B and PR C each state that they add their own manifest key § Revised migration plan
Open questions 🟩 question 9, identity across installs, decided under PR B if a consumer ever needs a store or an acceptance to follow the repo § Revised open questions
Audit 🟨 front matter re-audited at today's main, implementation-prs lists #11678; index row says #7181 is closed and names the three-PR split front matter; docs/request-for-change/README.md

🟩 added · 🟨 changed · 🟥 removed

Tests

Docs only. scripts/docs_lint.py, scripts/check_comment_history.py (base origin/main) and scripts/check_brand_name.py pass; the GPT and Opus local review lanes returned no findings on this diff.

Manual verification

Every claim about the implementation was checked against PR A's head 2532e2e8ff: _TOP_LEVEL_KEYS is the five keys named here, ProjectRegistry.add mints the id and matches an existing registration by normalized location, and test_project_manifest.py pins that id, mcp and memory are each refused by name.

Related Issues

Related: #3551 (Projects tracking issue), #11564 (Revision 2, merged), #11678 (PR A, which this text now describes).

no linked issue: the decision is recorded here and implemented in #11678; nothing else tracks it.

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 a review from a team September 18, 2026 16:30
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Intent: Record the maintainer's two decisions on the thin-Project manifest contract -- project.yaml carries no id (the registry assigns identity at add) and no mcp[] or memory.mode until PR B and PR C read them -- so PR A (#11678) and the RFC say the same thing before any manifest circulates.
Not a goal: Changing code or behaviour; deciding identity across installs (open question 9, PR B); reopening any Revision 2 decision that #11564 settled.

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

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 12b9d27

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

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

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify #11678's head still matches this text at its merge — the RFC now describes a moving PR, and the claims were pinned at 2532e2e8ff.

[DESIGN-REVIEWED] 12b9d27

@github-actions

github-actions Bot commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 12b9d27

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 18, 2026
… that reads them

The thin-Project manifest carries no id, mcp or memory key in PR A. The
registry mints the Project id at add and every install-local key hangs
off it; re-adding a registered location returns the existing
registration. memory.mode enters the schema with PR B and mcp[] with
PR C, because unknown keys are refused by name and admitting a key later
is compatible where retracting a parsed-but-unused one is not. Adds open
question 9 (identity across installs, decided under PR B), re-audits the
front matter and index row at today's main.
@kyleseaman
kyleseaman force-pushed the docs/rfc-projects-registry-id branch from ed24c14 to 12b9d27 Compare September 18, 2026 17:21
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Version skew: an older install meeting a newer manifest is unstated (span=f6f67c8586b7) -- fixed in 12b9d27

Decided in the text, the first way the item offered: an install that has not upgraded refuses a manifest carrying a key it does not know, loudly and by name, and upgrading is the remedy -- a Project is never half-honoured by an install that cannot act on what it declares. apiVersion stays crew.kiro/v1 across additive keys and moves only when a key is retracted or changes meaning. The PR body row for the manifest sketch names the rule.

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 18, 2026

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

Approved after a full read of the diff on the current head: the change matches the body and linked issue, every load-bearing claim was spot-checked against main, the failure paths were traced and fail safe, tests pin the behaviour, and every review-lane item on this head is either PASS or disposed.

@iamwhatever
iamwhatever merged commit b7b5663 into main Sep 18, 2026
123 of 125 checks passed
@iamwhatever
iamwhatever deleted the docs/rfc-projects-registry-id branch September 18, 2026 21:23
@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
… that reads them (kirodotdev#11828)

The thin-Project manifest carries no id, mcp or memory key in PR A. The
registry mints the Project id at add and every install-local key hangs
off it; re-adding a registered location returns the existing
registration. memory.mode enters the schema with PR B and mcp[] with
PR C, because unknown keys are refused by name and admitting a key later
is compatible where retracting a parsed-but-unused one is not. Adds open
question 9 (identity across installs, decided under PR B), re-audits the
front matter and index row at today's main.
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