m12-pr13: /context Living Engineering Brain (19 files)

[BalaShankar9]

Summary

/context/ Living Engineering Brain — 18 enterprise-grade markdown files (plus README index) that synthesize every concern in this codebase. Cross-references existing canonical sources (blueprint, ADRs, runbooks, repo memory) rather than duplicating them.

Doc PR — exempt from the ~600 LOC cap. Total ~7,500 LOC of markdown across 19 files.

Files

#	File	Concern
1	PROJECT_OVERVIEW	What HireStack AI is, who it serves
2	ARCHITECTURE	Component map, deployables, request lifecycle
3	FRONTEND	Next.js app, routes, state, dynamic imports
4	BACKEND	FastAPI app, route registry, services, middleware
5	DATABASE	Postgres tables, RLS, partitions, migrations
6	API	HTTP/SSE surface, contract types, idempotency
7	AUTH_SECURITY	JWT, RLS, capability tokens, prompt injection
8	DEVOPS_INFRA	Hosting, Docker, CI, deployment topology
9	AI	Pipeline, agents, chains, model router, cost
10	TESTING	Test pyramid, contracts, eval gates
11	PERFORMANCE	Latency budgets, hot paths, caching
12	FILE_TREE	Annotated repository map
13	BUSINESS_LOGIC	Domain rules, invariants, lifecycle states
14	TECH_DEBT	TD-1..TD-10 register synthesis
15	RELEASE_READINESS	Pre-deploy gates, rollout discipline
16	CHANGELOG_INTELLIGENCE	What shipped, when, why, links to PRs
17	KNOWN_ISSUES	Open bugs, watch list (W1..W15), gotchas
18	SCALABILITY_ROADMAP	Stage A/B/C plan, scaling triggers

Self-updating contract

• scripts/governance/check_context_freshness.py — advisory script; reads each file's YAML front-matter watch_paths + last_synced, runs git log --since=<last_synced> -- <watch_paths>, warns if commits exist. Always exits 0. Wired as make check-context.
• CONTRIBUTING.md gains a "Context system maintenance" section with a change-type → context-file map and a "what good /context maintenance looks like" checklist.
• Promotion of check-context to a required CI gate is tracked as KNOWN_ISSUES.md W14 (gated on noise rate < 30% over a month).

Front-matter contract

Every file begins with:

---
title: <Concern>
last_synced: 2026-05-08
watch_paths: [...]
canonical_sources: [...]
update_when: [...]
---

Then: H1 + tagline blockquote, "TL;DR — N lines" numbered list, sections, ending with a "What good X looks like" checklist.

Stacked on

PR #30 (m12-pr12-provider-failover-test).

Verification

$ python scripts/governance/check_context_freshness.py
checking 18 context files for staleness...
... (advisory warnings expected — last_synced=today, recent commits exist)
exit=0

[Copilot]

Pull request overview

Adds a new /context/ documentation system (“Living Engineering Brain”) plus a lightweight governance helper to detect when context docs may be stale relative to watched code paths.

Changes:

• Introduces 18 concern-focused /context/*.md documents plus context/README.md index with shared YAML front-matter conventions.
• Adds scripts/governance/check_context_freshness.py and wires it to make check-context.
• Updates CONTRIBUTING.md with guidance on when/how to maintain /context.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
scripts/governance/check_context_freshness.py	Adds advisory script to warn when watched paths changed since last_synced.
Makefile	Adds check-context target to run the advisory freshness checker.
CONTRIBUTING.md	Documents the /context maintenance workflow and update mapping.
context/README.md	Adds /context index and conventions for the documentation system.
context/PROJECT_OVERVIEW.md	High-level product/system overview context doc.
context/ARCHITECTURE.md	Architecture map and rules cross-referencing canonical blueprint/ADRs.
context/FRONTEND_CONTEXT.md	Frontend structure, SSE contract, and testing/deploy notes.
context/BACKEND_CONTEXT.md	Backend processes, middleware order, routes/services/workflows overview.
context/DATABASE_CONTEXT.md	DB/RLS/migration/partitioning discipline and key table inventory.
context/API_CONTEXT.md	Public HTTP/SSE surface and contracts (OpenAPI, idempotency, events).
context/AUTH_SECURITY_CONTEXT.md	Auth, RLS, SSRF, capability tokens, sandbox tiers, and security posture.
context/DEVOPS_INFRA_CONTEXT.md	Deployment topology, CI gates, staging mirror, and infra conventions.
context/AI_CONTEXT.md	AI engine boundaries, model routing, reliability primitives, tools/evals/observability.
context/TESTING_CONTEXT.md	Test pyramid, required gates, and local/CI testing conventions.
context/PERFORMANCE_CONTEXT.md	SLOs, latency/cost budgets, load testing, and perf guardrails.
context/BUSINESS_LOGIC_CONTEXT.md	Domain rules, pipeline phases, and user-visible surfaces/invariants.
context/TECH_DEBT.md	TD ledger synthesis with states, plans, and anchors.
context/RELEASE_READINESS.md	Stage A readiness checklist and P0/P1 status summary.
context/CHANGELOG_INTELLIGENCE.md	Engineering-facing changelog index tying PRs to memories/contexts/ADRs.
context/KNOWN_ISSUES.md	Watch list (W-items) and risk matrix with defenses/triggers.
context/SCALABILITY_ROADMAP.md	Stage A/B/C triggers and scaling plan.
context/FILE_TREE.md	Annotated repository map and “where do I put this?” cheat sheet.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.