Skip to content

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.md
index 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 the
canonical 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 shared
contract beyond the contributor change and should land or be reused
independently. The implementation pull request then rebases onto that decision.
diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.md
index 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: 2
kind: component
id: 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 questions
diff --git a/docs/templates/knowledge/versions.json b/docs/templates/knowledge/versions.json
index 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.mjs
index 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/,
);
});