[cixzhang]

Exact decision needed

Where do a native component's views and spec live when core keeps that component in another component's folder, as core keeps AvatarStatusDot in packages/core/src/Avatar/ and ListItem in packages/core/src/List/?

Existing authority searched

• AST-093 FR1 (current) gives each native component its own folder <Name>/, "as core does", and its spec <Name>/<Name>.spec.md. Read literally, that would separate a family member's native record from its family. But core doesn't do that: core keeps AvatarStatusDot in Avatar/ and ListItem in List/.
• The Swift AvatarStatusDot shipped with its view and spec in Sources/Astryx/Avatar/. The owner's recorded decision on that pull request approved keeping the spec beside its view in Avatar/, following core.
• architecture:knowledge-contracts INV27 places records but doesn't decide native family folders.
• Open work: the knowledge checks that enforce platform record placement (feat(knowledge): check every specification in the repository as a knowledge record, and convert the native specs #8288) and the Swift shared rules as records (docs(native): every Swift shared rule is an architecture record #8500). Neither changes FR1.

Decision

One rule, in the same words in both records:

• AST-093 FR1 opens: "Each native component's views and spec live in one folder of its language's implementation: the folder where core keeps the component, which is <Name>/ when core keeps it in its own folder, and core's folder otherwise (core's Avatar/AvatarStatusDot, List/ListItem)." The Swift path Sources/Astryx/<Name>/<Name>.spec.md is the common case. The rule also covers a component core keeps in a folder named for no component, such as i18n/InternationalizationProvider.
• FR1's verification row names the member case.
• architecture:knowledge-contracts Owning code: "A platform implementation's record instead sits in the folder where core keeps the component, which is <PublicName>/ when core keeps it in its own folder, and core's folder otherwise (spec:AST-093 FR1)." This is the counterpart of its parent/member consumer-doc rule, which native folders don't have.

Rejected alternatives

• Moving the Swift AvatarStatusDot to its own AvatarStatusDot/ folder. That would separate it from Avatar, where core and the shipped Swift view both keep it, against the recorded owner decision.

Claim scope and non-goals

The sentence governs only where a native component's views and record live when core keeps the component in another component's folder. Components core keeps in their own folder are unchanged.

Evidence and implementation relationship

• Core today: packages/core/src/Avatar/AvatarStatusDot.spec.md and packages/core/src/List/ListItem.doc.mjs.
• Swift today: packages/native/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md.
• feat(knowledge): check every specification in the repository as a knowledge record, and convert the native specs #8288's checker requires a platform record to sit in the folder where core keeps its component, and routes a member record only to its same-stem files there.

Writing rubric results

• R1 narration: none. The sentences state where the views and record live.
• R2 research in the record: none.
• R3 evidence naming a change: none.
• R4 rejected alternatives over one line or outside a decision: none in the record.
• R5 pull request or issue references remaining: none in the record.
• R6 ruled open questions still listing options: none.

Scope

• This PR contains specification records only.
• It records observable behavior and preserves equivalent internal implementations.
• Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
• Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
• It records one intentional durable decision, not a rescue for a separable tagalong.
• The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
• Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
• Public text and artifacts contain no internal Meta context.

Validation

• pnpm check:knowledge
• Prettier
• git diff --check

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 27, 2026 4:58am UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
❓ Needs maintainer input (for maintainers only)	Oct 27, 2026, 5:45 AM UTC

[github-actions]

PR Analysis Report

🔎 Preview · bbc5934

Storybook · Sandbox · built from this PR's head

Current run: The current CI run concluded failure. Current analysis is unavailable.

---

_{Generated by PR Enrichment workflow | View current CI run}

[astracat-bot]

Approval waits on an engineering owner's decision about the new AST-093 FR1 sentence on where a native component's record lives: an engineering owner records it by commenting /approve-spec ac12db4edade2da01bf9928fdd9326792ab7c4c7 on this pull request (the author may do so as an engineering owner), and a new commit needs the command again. Whatever the decision, these record fixes are needed:

• Read as written, the sentence applies only when core keeps a component's record in another folder, so ListItem and the other members core keeps without a record (Tab, TableRow and more) still get a native folder of their own, while the description, #8288's checker and #8370 put a Swift ListItem record in List/; if that is the intent, key the sentence on where core keeps the component.
• The sentence moves only the record while FR1 still opens with each native component having its own folder, so saying the member's views and record live in that folder would also cover the Swift Avatar/AvatarStatusDot.swift.
• The Owning code section of docs/architecture/knowledge-contracts.md still requires a consumer-doc entry in the folder for a parent/member record, which native folders don't have, so it needs the same exception for platform folders, or FR1 should defer to it.
• FR1's verification row should name the member case.

[Automated review]

[astracat-bot]

Read as written, this applies only when core keeps the component's record in another folder. Core keeps ListItem, Tab, TableRow and 25 other components in another component's folder with a consumer doc but no record, so FR1 still sends their native records to <Name>/, while the description's scope, #8288's checker and #8370 put a Swift ListItem record in List/. The sentence also moves only the record, though FR1's first sentence still gives each native component its own folder. If the description's scope is the intent, something like:

When core keeps a component in another component's folder (core's Avatar/AvatarStatusDot and List/ListItem), the native component's views and record live in that same folder.

[astracat-bot]

Approval waits on an engineering owner's decision on the new AST-093 FR1 sentence, its verification row and the matching knowledge-contracts Owning code sentence, which change two current records: an engineering owner records it by commenting /approve-spec <full head SHA> on this pull request (the author may do so as an engineering owner), and a new commit needs it again. The record fixes asked for on the earlier head are all in place. One fix remains whatever the decision: FR1 moves a native component only out of another component's folder, while the Owning code sentence and #8288's checker put every platform record wherever core keeps the component, so the two disagree for a component core keeps in a folder named for no component, such as i18n/InternationalizationProvider; state one rule in the same words in both records.

[Automated review]

[astracat-bot]

This reaches further than FR1's new sentence: FR1 moves a native component only when core keeps it in another component's folder, so a component core keeps in a folder named for no component (core's i18n/InternationalizationProvider) keeps <Name>/ under FR1 but goes to i18n/ here, and #8288's checker follows this wording. "Where core keeps" is also two folders for Heading (source Heading/, consumer doc Text/Heading.doc.mjs). One rule in the same words in both records would close it, for example:

a native component's views and record live in its core component's own folder when core has one, and otherwise in the folder where core keeps it

[astracat-bot]

Approval waits on an engineering owner's decision on the rewritten AST-093 FR1 opening, its verification row and the matching knowledge-contracts Owning code sentence, which change two current records: an engineering owner records it by commenting /approve-spec <full head SHA> on this pull request (the author may do so as an engineering owner), and a new commit needs it again. The fix asked for on the previous head is in place: both records now state one rule in the same words, so a component core keeps in a folder named for no component, such as i18n/InternationalizationProvider, gets the same folder from both. Nothing else is needed from the author.

[Automated review]

[cixzhang]

Superseded: native specs now live under docs/specs/components (#9007), so a native record's folder no longer depends on where core keeps its code.