[cixzhang]

Maintainer impact

Records under a package's specs/ directory, such as packages/native/specs/swift/library/tooltip.spec.md and the Swift architecture records an open pull request adds there, were invisible to the spec tooling. A broken record there (for example kind: bogus) passes pnpm check:knowledge, and an edit to a current one gets no spec-owner gate. Owners lose the gate on the Swift rules every native component follows, and nothing catches a malformed record.

Intended invariant

architecture:knowledge-contracts Owning code: "A record governing one package's cross-component rules lives under that package's specs/ directory as <slug>.spec.md, with kind architecture and an id of architecture: followed by the package name, each directory between specs/ and the file, and the slug, joined by hyphens." INV27 says every spec is a checked record. No product code or record content changes.

Change

• check:knowledge: discovery reads packages/<package>/specs/…/<slug>.spec.md. Each one is checked as any architecture record is (schema rules, sections, applicability blocks, ids, authority and approval). Then it checks that the kind is architecture and that the id is the one its path gives.
• Owner gate (change-scope.cjs): these records are knowledge records, owner-gated like docs/architecture/ and never spec-only.
• Guard: a current record with an unknown kind no longer crashes the reference check; the unknown kind is reported instead.
• Record: the architecture:knowledge-contracts enforcement-gap paragraph now says what is checked. The INV27 verification row names the change-scope test. Markdown under specs that is not a <slug>.spec.md (guidance files) stays a review-only gap.

Evidence

• Failure before the change: on main, changing kind: in packages/native/specs/swift/library/tooltip.spec.md to bogus prints "Knowledge templates and records are aligned."; classifyChanges returns touchesKnowledgeRecords: false for it.
• Success after the change: the same edit fails with "unknown knowledge kind" and "must be kind: architecture"; a wrong id fails with the path-derived id. A record there made current leaves the gate pending (spec waiting, eng), an edit to a draft one needs no approval, and README.md there is not a candidate (spec-owner-reconcile.test.mjs, change-scope.test.mjs).
• The open branch that adds 8 Swift architecture records there passes the new check unchanged; breaking one of them fails it.
• Product/runtime behavior verified unchanged: no package source changes; pnpm check:knowledge passes; specs:for --unreached returns 0.
• CI impact: no workflow, action, or job changes. Runner class, job-minutes per update, runner-pool usage, and time to green are unchanged; the added tests run in the existing node test job (a few seconds).

Scope

• No intended public API, product behavior, visual direction, or policy change.
• Product changes discovered during the work were removed or split.
• Public text and artifacts contain no internal Meta context.

Testing

• vitest --project node on knowledge-paths, change-scope, spec-owner-decision, spec-owner-reconcile, spec-owner-workflow, check-knowledge, and specs-for-file: 416 tests pass.
• pnpm check:knowledge and specs:for --unreached on main, and on the open branch that adds the Swift architecture records.

Writing rubric results

• R1 narration: none. The amended paragraph states what is checked, in the present tense.
• R2 research: none.
• R3 evidence names a change: the INV27 row names the tests that catch an invalid package record and a skipped gate.
• R4 rejected alternatives: none added.
• R5 PR/issue refs: none.
• R6 ruled open questions: none open.

Posted by Cindy's agent on her behalf.

[vercel]

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

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Nov 1, 2026 2:15pm UTC

[astracat-bot]

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Nov 1, 2026, 2:22 PM UTC

[cixzhang]

/approve-spec afb84cd

[github-actions]

PR Analysis Report

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

---

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

[astracat-bot]

Recommending approval. Records under packages/<package>/specs/…/<slug>.spec.md are now checked for kind and path-derived id and owner-gated, as the current architecture:knowledge-contracts placement rule and INV27 require, and the record edit has an engineering owner's approval for this exact commit. The before/after behaviour in the description reproduces, and the records in #8500 pass the new check unchanged. #8288 changes the same four files, so whichever lands second will need to reconcile them.

[Automated review]