diff --git a/AGENTS.md b/AGENTS.md index b8de3c0..ac63520 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -125,7 +125,7 @@ Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for- ### Domain docs -Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. +Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. ## Canonical references diff --git a/CLAUDE.md b/CLAUDE.md index 4753053..334c6aa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -132,7 +132,7 @@ Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for- ### Domain docs -Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. +Single-context: one `GLOSSARY.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. ## Canonical references diff --git a/CONTEXT.md b/GLOSSARY.md similarity index 100% rename from CONTEXT.md rename to GLOSSARY.md diff --git a/docs/agents/domain.md b/docs/agents/domain.md index 65ff6d2..0ddb3fa 100644 --- a/docs/agents/domain.md +++ b/docs/agents/domain.md @@ -2,13 +2,13 @@ How the engineering skills should consume this repo's domain documentation when exploring the codebase. -**This repo is single-context**: one `CONTEXT.md` (not yet written) and one `docs/adr/` at the repo root. There is no `CONTEXT-MAP.md` — don't go looking for per-context docs. +**This repo is single-context**: one `GLOSSARY.md` and one `docs/adr/` at the repo root. There is no `GLOSSARY-MAP.md`, so don't go looking for per-context docs. ## Before exploring, read these -- **`CONTEXT.md`** at the repo root, or -- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. -- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. +- **`GLOSSARY.md`** at the repo root, or +- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. @@ -18,36 +18,36 @@ Single-context repo (most repos): ``` / -├── CONTEXT.md +├── GLOSSARY.md ├── docs/adr/ │ ├── 0001-event-sourced-orders.md │ └── 0002-postgres-for-write-model.md └── src/ ``` -Multi-context repo (presence of `CONTEXT-MAP.md` at the root): +Multi-context repo (presence of `GLOSSARY-MAP.md` at the root): ``` / -├── CONTEXT-MAP.md +├── GLOSSARY-MAP.md ├── docs/adr/ ← system-wide decisions └── src/ ├── ordering/ - │ ├── CONTEXT.md + │ ├── GLOSSARY.md │ └── docs/adr/ ← context-specific decisions └── billing/ - ├── CONTEXT.md + ├── GLOSSARY.md └── docs/adr/ ``` ## Use the glossary's vocabulary -When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids. -If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). +If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). ## Flag ADR conflicts If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: -> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_ +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/architecture/snapshot-model.md b/docs/architecture/snapshot-model.md index 01922a3..282e178 100644 --- a/docs/architecture/snapshot-model.md +++ b/docs/architecture/snapshot-model.md @@ -264,7 +264,7 @@ The PII story will need refinement with a real security review. Documented now s | Write overhead | < 5ms per row | p99 latency added to agent writes by segment streaming | | Snapshot storage | < 2× changed data | Amortized over many snapshots | -These are the binding v1.0 numbers — see [`CONTEXT.md`](../../CONTEXT.md) for the commitment vs target-under-verification vocabulary. +These are the binding v1.0 numbers — see [`GLOSSARY.md`](../../GLOSSARY.md) for the commitment vs target-under-verification vocabulary. The point of committing to numbers publicly is so we don't ship a fast demo and a slow product. As of 2026-07-11, `rollback` < 5s is a **target under verification** at the committed shape (only measurement: 10.34 s on laptop-class hardware; cloud-class run tracked in diff --git a/docs/product/mvp-spec.md b/docs/product/mvp-spec.md index 140d805..d60b73e 100644 --- a/docs/product/mvp-spec.md +++ b/docs/product/mvp-spec.md @@ -88,7 +88,7 @@ If a feature isn't in the demo path, it doesn't ship in MVP. The 1M-row criteria are not yet verified at the committed shape: snapshot measures green so far (18.81 ms @ 1M rows, laptop, approximated shape), but rollback measures 10.34 s @ 1M rows on laptop-class hardware — - a **target under verification** per [`CONTEXT.md`](../../CONTEXT.md), + a **target under verification** per [`GLOSSARY.md`](../../GLOSSARY.md), with the cloud-class run tracked in [issue #132](https://github.com/git-agentic/git.agentic/issues/132). See [`benchmarks.md`](../architecture/benchmarks.md) for the measurements. - **Narrative:** A blog post / video showing the broken-prompt demo that explains the wedge clearly enough that a hostile-but-fair YC partner gets it in under 90 seconds.