Checklist
Summary
- Current state: main has import-linter configuration, CONTRIBUTING rules, stable-contract tests, and architecture contract tests, but the implementation repo does not yet carry the complete executable boundary map and release-gate toolchain from the architecture package.
- Goal: Add glossary for facts queries engines packs and projections through Architecture governance and executable conformance. Inputs are limited to the normative summary, ADRs, contracts, and current package names; make the named rule executable whenever a static/import/test check is feasible; a prose-only statement does not satisfy the issue.
Affected Area
Release: R1 foundations
Area: docs
Dependencies:
Change
Required change:
- Input boundary: The change must accept only the normative summary, ADRs, contracts, and current package names.
- Required output: The change must produce one cross-linked glossary defining facts, snapshots, QueryViews, engines, packs, projections, hosts, and compatibility terms.
- Define each architecture term once using the normative summary and contract names; distinguish durable owners, data values, projections, adapters, and temporary compatibility code.
- List deprecated or ambiguous legacy terms with their approved replacement and the owning migration issue; do not silently redefine an existing public product term.
- Cross-link every term to its governing ADR/contract and to the current package when one exists; mark future package names as planned.
- Keep the glossary consumable by the terminology drift scanner through stable headings or a documented machine-readable table.
Include:
- The named document/artifact only.
- Current, legacy, and planned ownership plus links to the exact executable gate or follow-up issue.
Out of scope:
- Do not include unrelated cleanup, a new diagnostic rule, or a second architecture owner.
- Do not change CLI/API signatures, diagnostic code, severity, text, spans, ordering, schemas, baseline/suppression behavior, discovery, or file ordering unless this issue explicitly owns a versioned SchemaHost migration.
Likely files:
docs/architecture/glossary.md
00-start-here/normative-summary.md
tools/architecture/
tests/test_architecture_contracts.py
Test Notes
Acceptance checks:
Compatibility notes:
No public behavior change. Any public behavior drift needs a linked SchemaHost/versioned compatibility issue.
Checklist
Summary
Affected Area
Dependencies:
R1-066Change
Required change:
Include:
Out of scope:
Likely files:
docs/architecture/glossary.md00-start-here/normative-summary.mdtools/architecture/tests/test_architecture_contracts.pyTest Notes
Acceptance checks:
The artifact states the input boundary, required output, owner, and out-of-scope work without presenting planned code as current.
Each requirement above is traceable to text and, where enforceable, to an executable gate or linked issue.
All repository-relative links resolve; terminology matches the cited ADRs/contracts.
Run
git diff --check; verify every new repository-relative Markdown link resolves from its containing file.Run
python -m pytest tests/test_architecture_contracts.py tests/test_contract_readiness.py -qwhen the document changes an enforced ownership, term, or release-gate assertion.Evidence: Glossary terms match the normative summary and contract names.
Evidence: Terminology drift check rejects deprecated owner names.
Compatibility notes:
No public behavior change. Any public behavior drift needs a linked SchemaHost/versioned compatibility issue.