Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(knowledge): every current record is reachable from a path; records declare paths no other link reaches (#7794)

Cindy Zhangd4ade4a0456d
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index cd9916d477..34b7845628 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -20,6 +20,7 @@ applies_to:
verified_by:
[
scripts/check-knowledge.test.mjs,
+ scripts/specs-for-file.test.mjs,
.github/scripts/change-scope.test.mjs,
.github/scripts/component-design-decisions.test.mjs,
.github/scripts/lib/classify-visual.test.mjs,
@@ -47,8 +48,11 @@ deciding_specs: []
"INV18",
"INV20",
"INV21",
+ "INV25",
+ "INV26",
"DEC-9",
- "DEC-10"
+ "DEC-10",
+ "DEC-12"
]
}
}
@@ -99,6 +103,19 @@ changed code or theme source
→ mapped tests and audit evidence
```
+A lookup can also start from any repository path. `pnpm specs:for <path>`
+lists every current record linked to that path, the system specs that decided
+those records, and the global claims the path's component triggers route. It
+follows only links that records and files declare:
+
+- placement: the record itself, the component, module, or theme record whose
+ canonical location contains the path;
+- path fields: `applies_to`, `verified_by`, and `path-applicability:v1` patterns;
+- names: family `members`, design `components`, and `affects_consumer_docs` ids
+ naming the path's component or consumer-doc topic;
+- citations: a system-spec number such as `AST-030` written in the file;
+- inheritance: the references a linked record relies on.
+
A current record may cite a previous human decision. When the new case is within
that decision's stated scope, the reviewer applies it without asking again.
@@ -283,6 +300,43 @@ Every record is either:
visual-regression execution and baseline adoption. This placement rule does
not add a capture owner or require permanent archiving of every CI run.
+### Path discovery
+
+- **INV25 — Every current record is reachable from a path.** Each current record
+ is linked from at least one repository path that is not itself a knowledge
+ record, through placement, a path field, a name, a citation, inheritance, or
+ a deciding link. A path-first lookup reports a path with no linked record as
+ unrouted. It never infers a link from a file name, extension, or directory
+ name.
+- **INV26 — Path applicability locates a record; claims still decide.** A record
+ whose rules apply to paths that no other link reaches declares them in one
+ `path-applicability:v1` block. A matching path lists the record. The match
+ does not widen any claim beyond its stated scope (INV14), does not make the
+ record outrank a narrower owner (INV9), and does not require behavior to live
+ in the named files (INV18). Every pattern matches at least one tracked file.
+
+## Path applicability
+
+Use this optional block when a record governs paths that its placement, path
+fields, names, and inherited links do not reach. A record that is already
+reached from every path it governs stays unmarked.
+
+<!-- path-applicability-example:v1 -->
+
+```json
+{
+ "paths": ["apps/docsite/**", "packages/**/*.doc.mjs"]
+}
+```
+
+In an opted-in record, replace the example marker with `path-applicability:v1`.
+Patterns are repository-relative and case-sensitive. `**` is a whole segment
+that spans any number of segments, `*` matches within one segment, and `?`
+matches one character within a segment. Patterns use only letters, digits,
+`_ . @ - /`, and those wildcards. A bare `**` is rejected. The checked-in
+validator rejects malformed blocks, unsafe or repeated patterns, and patterns
+that match no tracked file.
+
## Global review applicability
Use this optional block only when named claims apply across otherwise unrelated
@@ -619,7 +673,11 @@ this flow passes the historical review benchmark and is enforced on pull request
canonical record; `docs/themes/README.md` is guidance and an index only.
- `docs/schemas/knowledge/` defines required structure.
- `scripts/check-knowledge.mjs` validates templates, records, approval metadata,
- and optional component/module design-decision tables.
+ optional component/module design-decision tables, `path-applicability:v1`
+ blocks, and INV25 reachability.
+- `scripts/specs-for-file.mjs` (`pnpm specs:for`) resolves the records linked to
+ a path. `--unrouted` lists tracked paths with no linked current record;
+ `--unreached` lists current records no path reaches.
- `.github/scripts/component-design-decisions.cjs` classifies current
component/module changes as no DD change, DD-only, or mixed from trusted base
and head bytes. DD-only requires unchanged path, kind, authority, and every byte
@@ -863,6 +921,23 @@ Rejected: counting any app approval on the pull request, because an approval of
an earlier head or one followed by a request for changes would keep the gate
clear.
+### DEC-12 — Records declare the paths they govern in an optional overlay
+
+**Reference:** `architecture:knowledge-contracts/DEC-12`
+**Decider:** `cixzhang`, `2026-10-21`
+
+A record that governs paths no other link reaches declares glob patterns in an
+optional `path-applicability:v1` block, beside `review-applicability:v1`. The
+overlay is independently versioned, so opting in does not change a record
+kind's required shape or migrate other records. A path-first lookup lists a
+matched record; claim scope, precedence, and implementation freedom are
+unchanged.
+
+Rejected: a required `applies_to` field on every kind, because it would migrate
+every active record to declare paths most already reach through placement or
+inheritance. Rejected: regular expressions, because a reviewer cannot read
+their reach at a glance and they over-match silently.
+
## Verification
| Invariant | Evidence | Failure signal |
@@ -881,9 +956,10 @@ clear.
| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |
| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |
-| Invariant | Evidence | Failure signal |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV22–INV24 | Contributor/reviewer evidence inventory; public-link and byte verification; retained remote refs; unchanged fixture/baseline/media paths | Disposable captures enter the source tree, cleanup loses a referenced image, a temporary branch is called durable, or storage changes overwrite an owner's proof or retention contract |
+| Invariant | Evidence | Failure signal |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV22–INV24 | Contributor/reviewer evidence inventory; public-link and byte verification; retained remote refs; unchanged fixture/baseline/media paths | Disposable captures enter the source tree, cleanup loses a referenced image, a temporary branch is called durable, or storage changes overwrite an owner's proof or retention contract |
+| INV25, INV26, DEC-12 | `scripts/specs-for-file.test.mjs`, `scripts/check-knowledge.test.mjs`, and `pnpm check:knowledge` | A current record is reached by no tracked non-record path, a lookup infers a link from a name, a pattern matches nothing or the whole repository, or a pattern match widens a claim or outranks a narrower owner |
Evidence placement is enforced by contributors and reviewers. The local
`docs/pr-assets/` ignore prevents accidental staging; it is not a blocking CI
diff --git a/docs/specs/AST-030/spec.md b/docs/specs/AST-030/spec.md
index 3a81a65bd5..320827251f 100644
--- a/docs/specs/AST-030/spec.md
+++ b/docs/specs/AST-030/spec.md
@@ -29,6 +29,19 @@ affects_consumer_docs: []
}
```
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": [
+ ".github/workflows/**",
+ ".github/scripts/change-scope.*",
+ ".github/scripts/*routing*.test.mjs",
+ ".github/scripts/pr-scope-touches.*"
+ ]
+}
+```
+
## Intent
Route pull-request checks from the repository surfaces a change can affect rather
diff --git a/docs/specs/AST-033/spec.md b/docs/specs/AST-033/spec.md
index 16ec57fab7..72cff51896 100644
--- a/docs/specs/AST-033/spec.md
+++ b/docs/specs/AST-033/spec.md
@@ -44,6 +44,14 @@ affects_consumer_docs: [docsite]
}
```
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": ["apps/docsite/**"]
+}
+```
+
## Intent
People using the Astryx Docsite should see truthful projections of the owning
diff --git a/docs/specs/AST-041-consumer-docs-audience/spec.md b/docs/specs/AST-041-consumer-docs-audience/spec.md
index 3d85f6cf51..c20ef65419 100644
--- a/docs/specs/AST-041-consumer-docs-audience/spec.md
+++ b/docs/specs/AST-041-consumer-docs-audience/spec.md
@@ -18,6 +18,18 @@ affects_consumer_docs: [is-my-code-good]
# Consumer documentation audience boundary system spec
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": [
+ "packages/cli/assets/docs/**",
+ "packages/**/*.doc.mjs",
+ "packages/**/*.doc.*.mjs"
+ ]
+}
+```
+
## Intent
Documentation that Astryx ships to callers serves people and agents building
diff --git a/docs/specs/AST-042-cli-command-admission/spec.md b/docs/specs/AST-042-cli-command-admission/spec.md
index 3088cd7d53..d2d304c37c 100644
--- a/docs/specs/AST-042-cli-command-admission/spec.md
+++ b/docs/specs/AST-042-cli-command-admission/spec.md
@@ -18,6 +18,14 @@ affects_consumer_docs: []
# CLI command admission and programmatic parity system spec
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": ["packages/cli/clients/cli/**", "packages/cli/api/**"]
+}
+```
+
## Intent
Agents learn the Astryx CLI from its help, its manifest, and their own notes, and
diff --git a/docs/specs/AST-067-wall-time-resolution/spec.md b/docs/specs/AST-067-wall-time-resolution/spec.md
index 71081a0c9e..85dcaec1f8 100644
--- a/docs/specs/AST-067-wall-time-resolution/spec.md
+++ b/docs/specs/AST-067-wall-time-resolution/spec.md
@@ -18,6 +18,17 @@ affects_consumer_docs: []
# Wall-clock time resolution system spec
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": [
+ "packages/core/src/utils/plainDate.ts",
+ "packages/lab/src/Schedule/**"
+ ]
+}
+```
+
## Intent
People who see dates and times in a chosen time zone, such as a Schedule week or
diff --git a/docs/specs/AST-071-styling-library-compat/spec.md b/docs/specs/AST-071-styling-library-compat/spec.md
index 917f0c5bdb..3e4de53cb6 100644
--- a/docs/specs/AST-071-styling-library-compat/spec.md
+++ b/docs/specs/AST-071-styling-library-compat/spec.md
@@ -18,6 +18,20 @@ affects_consumer_docs: []
# Styling-library compatibility system spec
+<!-- path-applicability:v1 -->
+
+```json
+{
+ "paths": [
+ "packages/core/src/**",
+ "packages/lab/src/**",
+ "packages/charts/src/**",
+ "packages/richtext/src/**",
+ "packages/vega/src/**"
+ ]
+}
+```
+
## Intent
A product styles Astryx components with whatever its codebase already uses: