Skip to content

R1-067: Add glossary for facts queries engines packs and projections #208

Description

@1sgtpepper

Checklist

  • This fits the named release or area.
  • This is small enough for one focused PR.
  • Relevant checks are listed below.

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:

  • R1-066

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:

  • 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 -q when 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsUser and contributor documentation.enhancementNew feature or requestneeds designNot ready for implementation.p2Medium-priority issue.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions