Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture Consistency Guardrails

​

Goals

• Prevent reintroduction of cyclic and forbidden dependencies.
• Prevent cross-feature coupling through non-public feature internals.
• Ensure every source area is explicitly owned.
• Enforce semver-governed feature public contracts.
• Surface architecture risk trend signals directly in PRs.
• Keep rollout safe with no-regression baselines where full cleanup is still in progress.

​

Guardrails

​

1. Dependency Architecture Gate

• Command: npm run check:architecture
• Backed by dependency-cruiser (.dependency-cruiser.cjs)
• Baseline file: config/architecture-violations-baseline.json
• Report: artifacts/architecture-report.json

​

2. Feature Public API Gate

• Command: npm run check:feature-public-api
• Rule: Imports to @/features/<feature>/... from outside that feature must go through the feature public API (@/features/<feature> or @/features/<feature>/index).
• Extension: Stable sub-entrypoints can be explicitly declared as public in config/feature-public-api-allowlist.json (for example context or service facades that are part of the supported feature contract).
• Baseline file: config/feature-public-api-violations-baseline.json
• Report: artifacts/feature-public-api-report.json

​

2.1 Feature Hook Contract Gate

• Command: npm run check:feature-hook-contracts
• Rule:
  • Feature hooks exported from src/features/*/public.ts must be documented in docs/engineering/api-reference/hooks-reference.md.
  • Public feature hook source files must not import Firebase directly; server-backed hooks must delegate to services.
• Report: artifacts/feature-hook-contract-report.json

​

3. Layer Ownership Coverage Gate

• Command: npm run check:layer-ownership
• Rule: Every source file under src/ must match an ownership mapping entry.
• Ownership mapping: config/layer-ownership.json
• Report: artifacts/layer-ownership-report.json

​

4. Review Routing with CODEOWNERS

• File: .github/CODEOWNERS
• Rule: Architectural ownership paths in config/layer-ownership.json are mirrored in CODEOWNERS so PR review assignment follows the same boundaries.

​

5. Public Contract Semver + Changelog Gate

• Command: npm run check:public-api-contracts
• Rule:
  • Every src/features/*/public.ts must declare PUBLIC_API_VERSION in semver format.
  • Removing exports from a feature public contract is treated as breaking.
  • Breaking changes must include a major PUBLIC_API_VERSION bump.
  • Breaking changes must include a changelog entry in docs/engineering/api-reference/changelog-public-api.md.
• Baseline file: config/public-api-contract-baseline.json
• Report: artifacts/public-api-contract-report.json

​

6. Auto-Generated Public API Contract Docs

• Generate: npm run docs:public-api:generate
• CI sync check: npm run docs:public-api:check
• Output directory: docs/engineering/api-reference/public-api/
• Source of truth: src/features/*/public.ts

​

7. Runtime Architecture Guard Assertions (Dev/Test)

• Generator command: npm run architecture:runtime-guards:generate
• Runtime assertion modules:
  • App bootstrap: src/index.tsx
  • Test bootstrap: tests/setup.ts
• Behavior:
  • Dev/test throws early when new architecture violations or new cross-feature private-import violations are detected against baselines.
  • Production runtime is unaffected.

​

8. Architecture Risk Scoring + PR Summary

• Command: npm run check:architecture:risk
• Signals:
  • cycle violations
  • cross-feature dependency edges
  • cross-feature private edges
  • baseline debt trend vs base branch
• Outputs:
  • artifacts/architecture-risk-report.json
  • artifacts/architecture-risk-summary.md
  • Appends summary to GITHUB_STEP_SUMMARY in CI
• Branch budgets:
  • Config file: config/architecture-risk-budget.json
  • develop: warning when score exceeds configured threshold.
  • main: fail when score exceeds configured threshold.

​

9. Architecture Risk History Artifact

• Command: npm run check:architecture:risk:history
• Output:
  • artifacts/architecture-risk-history.json
  • artifacts/architecture-risk-history.csv
  • artifacts/architecture-risk-history.md
• Window: last N commits (--limit, default 20) with score + debt baseline trend.

​

10. BaseService Adoption Gate

• Command: npm run check:base-service-adoption
• Rule: Service files that import Firestore CRUD/query helpers directly must extend BaseService or ExtensionBaseService so they inherit standardized error handling, EventBus emission, audit logging, tenant scoping, and quota enforcement.
• Detection includes:
  • static imports from firebase/firestore
  • dynamic import('firebase/firestore') usage of CRUD/query helpers
  • imports from internal Firestore helper entrypoints such as @/core/firestore*
• Scope:
  • src/core/**
  • src/shared/**
  • src/features/**
  • src/extensions/**
• Baseline file: config/base-service-adoption-baseline.json
• Report: artifacts/base-service-adoption-report.json
• Companion gates:
  • npm run check:base-service-adoption:budget
  • npm run check:base-service-adoption:approval

​

11. Extension EventBus Subscription Gate

• Command: npm run check:extension-eventbus-subscriptions
• Rule: Source files under src/extensions/** must not subscribe with raw EventBus.on() or onAny() on the global bus or injected IEventBus references.
• Required patterns:
  • createExtensionEventBus(extensionId).on(...)
  • ExtensionBaseService.subscribeToEvent(...)
• Goal: prevent orphaned listeners that survive extension deactivation.

​

12. TypeScript No-Regression Gates

• Commands:
  • npm run check:types-baseline
  • npm run check:types:baseline:approval
  • npm run check:types:libcheck-baseline
• Rule:
  • check:types-baseline tracks the broader core/shared/services TypeScript surface from tsconfig.ci.json.
  • check:types:baseline:approval forces explicit PR acknowledgement when either TypeScript baseline file changes.
  • check:types:libcheck-baseline tracks the same surface with skipLibCheck: false via tsconfig.libcheck.json.
  • Both are no-regression gates: existing debt is baselined, but new errors fail CI.
• Baseline files:
  • config/typescript-errors-baseline.json
  • config/typescript-libcheck-baseline.json

​

Baseline Management

• Use --update-baseline only when intentionally accepting the current state as migration debt.
• Any baseline update should be reviewed alongside a rationale in the PR description.
• TypeScript baseline changes must be explicitly approved in CI before merge.
• BaseService baseline changes must be explicitly approved in CI before merge.
• Priority is to burn down baseline entries over time, not keep them static.

​

13. Agent Service Attribution Gate

• Command: npm run check:agent-service-attribution
• Rule:
  • Built-in agent tool callbacks and extension agent handlers must pass context.agentContext when they call write-capable service methods.
  • The check is intentionally conservative and targets likely mutation verbs on *Service receivers.
• Goal: prevent agent-triggered writes from being attributed to system/service identities instead of the originating human.

​

CI Integration

• architecture-report
• feature-public-api-report
• feature-hook-contract-report
• public-api-contract-report
• layer-ownership-report
• architecture-risk-report
• base-service-adoption-report
• TypeScript no-regression gates for both the broad core slice and the skipLibCheck: false slice

​

Debt Budget Policy

• Command: npm run check:feature-public-api-budget
• Rule:
  • Fail if config/feature-public-api-violations-baseline.json count increases vs base branch.
  • Emit CI warning if the count does not decrease.
• Goal: ensure cross-feature internal import debt trends downward release-over-release.
• Command: npm run check:base-service-adoption:budget
• Rule:
  • Fail if config/base-service-adoption-baseline.json adds any entries vs base branch.
  • Emit CI warning if the baseline does not decrease.
• Goal: ensure BaseService bypass debt only moves downward.

​

Migration Strategy

1. Freeze regressions with current baselines.
2. Reduce violations feature-by-feature.
3. Regenerate baselines only after deliberate debt-reduction milestones.
4. Remove baselines once each guardrail reaches and sustains zero violations.