gramps
c9ac348976
ai.md 228 → 64 lines. It now carries only: what the product is, the build commands, the architecture table, a "where the truth lives" table, and a pointer to HANDOFF. No narrative, no status, no duplicated invariants. AGENTS.md (195 lines) is now the single always-read file: - the 20 invariants that break output, wipe user data, or ship a legal/trust breach — one line each, pointing at the doc that explains it (they replace 110 lines of invariant stubs that duplicated docs/ai/*.md verbatim) - Response style + No-Fluff Mode moved in from ai.md (rules belong in the rules file) - onboarding is now: HANDOFF → ai.md router → the ONE docs/ai file → dir index; TASKS.md is read when the question is "what's next", not to write code - memory rides with the change but is no longer a unit of its own; HANDOFF is ≤40 lines and overwritten, never appended Anti-rebloat gate: scripts/verify.sh gains step 1/4, a doc-budget check (AGENTS ≤210, ai ≤100; HANDOFF/TASKS caps land with the queue trim). A commit that pads a capped file instead of moving detail fails the gate. schema.md and docs/index.md corrected for the new roles and reading order. Docs-only unit: scope-check run, no build.
61 lines
3.8 KiB
Markdown
61 lines
3.8 KiB
Markdown
# ytLlive — Memory Map (schema)
|
|
|
|
This file defines how the repo stores durable, associative memory: context as
|
|
plain markdown files, versioned in git. It is the map of the map — the schema
|
|
that every other memory file follows. Read `ai.md` first; this file explains
|
|
*why* and *how*.
|
|
|
|
## Why markdown files, not a database
|
|
|
|
- Grep-able, diffable, portable, human-editable — no tooling lock-in.
|
|
- Git gives versioning and history for free; every stale fact is a `git log` away.
|
|
- Files form a graph: each file is a node, each relative link an edge. The map
|
|
stays associative (like memory) rather than a rigid tree.
|
|
|
|
## File inventory
|
|
|
|
| File | Role | Entry point? |
|
|
|------|------|--------------|
|
|
| `AGENTS.md` | Auto-read on-ramp: working rules, **the invariants that break the product**, response style | **always read first** |
|
|
| `ai.md` | **Router** — what the product is, the architecture table, a "where the truth lives" table. No narrative, no status (≤100 lines, gated) | yes — the map |
|
|
| `README.md` | Human-facing intro: what the app is, how to run it, roadmap | no |
|
|
| `TASKS.md` | The active queue. Full task detail and research live in [`TASKS/`](TASKS/); done work in `TASKS/archive.md` | when the task is "what's next" |
|
|
| `HANDOFF.md` | Current operational state: branch, in flight, next action, landmines (≤40 lines, overwritten never appended) | yes — trust it as current state |
|
|
| `MyMistakes.md` | Failure log **+ RECIPES REGISTRY**: one-off solutions / how-tos get recorded here the same session, then grepp'd before ever re-deriving them | grep first on any "did this before?" wall |
|
|
| `schema.md` | This file: the conventions below | when in doubt |
|
|
| `<dir>/index.md` | Per-directory map (progressive disclosure): what lives there + links | when diving into code |
|
|
| `docs/ai/*.md` | **Subsystem truth** — one file per subsystem (capture, frame pipeline, output, overlays, youtube-api, ui-surface, product, environment). `ai.md` routes; [`docs/ai/index.md`](docs/ai/index.md) lists them with a "read when" | when the task touches that subsystem |
|
|
| `Views/` | Reserved for Views; currently empty | — |
|
|
|
|
## Conventions
|
|
|
|
1. **Semantic filenames.** A file's name says what it is (`YouTubeAuthService.cs`,
|
|
`FocusPreservingListBox.cs`). No codes, no abbreviations. Naming beats search.
|
|
2. **One `index.md` per code directory.** The index is a Map of Content (MOC):
|
|
it lists every file in that directory with a one-line purpose and links out to
|
|
related directories. Details live in the files, never duplicated in the index.
|
|
3. **Links over hierarchy.** Prefer relative links between related files over
|
|
deep nesting. Relationships that matter should be visible from `ai.md` or an
|
|
`index.md`; a note that is unreachable from `ai.md` might as well not exist.
|
|
4. **Stale facts get FIXED, not appended.** A wrong map is worse than no map.
|
|
When the code changes, update the memory file in the same change — no
|
|
"TODO: update later" notes.
|
|
5. **Progressive disclosure.** Don't cram detail into `ai.md`. `ai.md` names
|
|
concepts and points at files; the indexes and source are the detail. Each
|
|
layer adds resolution only when you drill in.
|
|
|
|
## Reading order
|
|
|
|
1. `AGENTS.md` — auto-read on-ramp: rules + invariants; it points you here.
|
|
2. `HANDOFF.md` — current state. Trust it; don't re-derive it.
|
|
3. `ai.md` — the router: architecture and where truth lives.
|
|
4. The one `docs/ai/*.md` file that matches the task.
|
|
5. `<dir>/index.md` — before reading that directory's files.
|
|
6. The source files themselves — always the authority over any memory file.
|
|
|
|
## Integration rule
|
|
|
|
Every feature change ships with what it **falsifies** corrected in the same commit — a path, an
|
|
invariant, a status line. Broader restatement may be batched at a milestone. The point is that
|
|
the map never stays wrong; it is not a tax on every commit.
|