An open source design system that's fully customizable and agent ready
TypeScript
docs: record only durable decisions (#5730)
Cindy Zhanga400ffc38be2
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 17e0ac04de..9fc97f061c 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -144,6 +144,17 @@ independently.Review comments are evidence of the conversation; the checked-in record is thecanonical decision.+Record the durable outcome, not the review transcript. A ruling belongs in a+canonical record when at least one is true:++- it changes or clarifies an owning component, family, or system boundary;+- it establishes a requirement or prohibition future work must preserve; or+- it rejects an alternative that is consequential and likely to recur.++A prop name, implementation mechanism, or failed visual experiment from an+abandoned pull request stays in review history unless that detail itself passes+this test.+Use a separate lower spec pull request only when the ruling changes a sharedcontract beyond the contributor change and should land or be reusedindependently. The implementation pull request then rebases onto that decision.diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.mdindex 16883c380b..209c5ae985 100644--- a/docs/templates/knowledge/component-spec.md+++ b/docs/templates/knowledge/component-spec.md@@ -1,6 +1,6 @@---schema_version: 1-template_version: 1+template_version: 2kind: componentid: component:<Name>authority: draft@@ -111,6 +111,8 @@ do not edit an existing component contract merely to backlink to a draft.## Decision log+<!-- Record a durable boundary or requirement, not a review transcript. Keep a rejected alternative only when it is consequential and likely to recur. -->+### DEC-1 — `<component-local decision>`**Reference:** `component:<Name>/DEC-1`@@ -118,7 +120,7 @@ do not edit an existing component contract merely to backlink to a draft.`<Reason and user impact.>`-Rejected: `<alternative — why>`.+Rejected: `<include only when the alternative is consequential and likely to recur; otherwise delete this line>`.## Open questionsdiff --git a/docs/templates/knowledge/versions.json b/docs/templates/knowledge/versions.jsonindex 455391dff5..c7f2d44759 100644--- a/docs/templates/knowledge/versions.json+++ b/docs/templates/knowledge/versions.json@@ -1,6 +1,6 @@{"architecture": 1,- "component": 1,+ "component": 2,"design": 1,"family": 1,"implementation-plan": 1,diff --git a/scripts/check-knowledge.test.mjs b/scripts/check-knowledge.test.mjsindex 55f2d2d53f..bba323ff55 100644--- a/scripts/check-knowledge.test.mjs+++ b/scripts/check-knowledge.test.mjs@@ -252,10 +252,10 @@ describe('knowledge validation', () => {fs.mkdirSync(directory);fs.writeFileSync(path.join(directory, 'Button.spec.md'),- componentRecord({template_version: '2'}),+ componentRecord({template_version: '3'}),);expect(validateKnowledgeRoot(root).join('\n')).toMatch(- /template_version 2 is newer than 1/,+ /template_version 3 is newer than 2/,);});