68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
# Dev Brain schema
|
||
|
||
The registered projects are authoritative. This vault is a derived, human-readable wiki.
|
||
|
||
## Managed paths
|
||
|
||
DS4Server manages `purpose.md`, `schema.md`, `index.md`, `skills.md`, `log.md`, and topic pages below `projects/`, `subsystems/`, `concepts/`, `decisions/`, `invariants/`, `workflows/`, and `skills/`. Topic pages must opt in with `dev_brain: true`. Other notes, hidden files, Obsidian settings, attachments, and trash are never modified.
|
||
|
||
## Topic frontmatter
|
||
|
||
```yaml
|
||
---
|
||
dev_brain: true
|
||
type: subsystem # project, subsystem, concept, decision, invariant, workflow, or skill
|
||
project: Registered project name
|
||
status: verified # verified, stale, or needs-review
|
||
verified_at: 2026-07-27T12:00:00Z
|
||
sources:
|
||
- project: Registered project name
|
||
path: src/example.rs
|
||
symbol: optional_symbol
|
||
revision: latest-commit-containing-this-file-content
|
||
# For a clean tracked file, use `git log -1 --format=%H -- src/example.rs`,
|
||
# or a unique lowercase hex prefix of at least 7 characters. Use hash when
|
||
# this file differs from HEAD, is untracked, or the registered project is not Git.
|
||
---
|
||
```
|
||
|
||
`project` names a registered project, not this Dev Brain vault; `dev_brain_info` lists the exact registered names and folders. Each source `path` is relative to that registered project's folder; never resolve it inside the vault. Cite only files that support the page's claims, not every dirty file in the project. Each source has exactly one evidence version: `revision` or a lowercase SHA-256 `hash`. A revision is the newest commit that changed that source file, returned by `git log -1 --format=%H -- path`; validation requires that per-file revision and compares its file content with the current clean file. Every source therefore has its own revision; never stamp all sources with the repository's overall HEAD. Use a hash when that specific file differs from HEAD, is untracked, or its registered project is not Git.
|
||
|
||
## Skills
|
||
|
||
Skills are on-demand instructions stored as one Markdown file per skill below `skills/`. They use the same provenance and status fields as topic pages, set `type: skill`, and additionally require `name` and `description` frontmatter. Names contain 1–64 lowercase letters, digits, or hyphens, with no leading, trailing, or consecutive hyphens. Descriptions contain 1–1024 characters and explain both what the skill does and when to use it. Only skills whose status and current evidence are both `verified` appear in generated `skills.md` and the session system prompt. The prompt exposes each verified skill's name, description, and Markdown path; read the complete matching file on demand before following it. `index.md` lists all managed topic pages, while `skills.md` lists verified skills only. Do not hand-edit either generated index.
|
||
|
||
Files with `built_in: true` are app-managed skills restored from the DS4Server bundle. Do not create or edit them by hand.
|
||
|
||
```yaml
|
||
---
|
||
dev_brain: true
|
||
type: skill
|
||
name: review-release
|
||
description: Verify a release candidate against the project checklist. Use before publishing a release.
|
||
project: Registered project name
|
||
status: verified
|
||
verified_at: 2026-07-27T12:00:00Z
|
||
sources:
|
||
- project: Registered project name
|
||
path: docs/releasing.md
|
||
revision: full-or-unique-short-clean-git-revision
|
||
---
|
||
```
|
||
|
||
## Compilation
|
||
|
||
Read the purpose first. Examine high-signal manifests, documentation, schemas, entry points, public interfaces, and tests. Create the smallest coherent topic set that answers the purpose; do not mirror every source file. Use ordinary Obsidian wikilinks and embeds to connect topics.
|
||
|
||
## Querying
|
||
|
||
Start with `index.md` or ranked search, then follow links and backlinks. A `verified` page is authoritative only while all recorded evidence is current. Treat `stale` pages as navigation leads and `needs-review` pages as explicit uncertainty; check project sources before making claims from either.
|
||
|
||
## Refresh and semantic validation
|
||
|
||
When validation reports drifted sources, handle each listed file independently: re-read it, compare its current behavior with the page's documented findings, update, split, merge, or retire affected knowledge, then update only that source's revision or hash. For a large revision-backed file, `git diff <recorded-revision> -- path` shows the change from the recorded evidence to the current working-tree version; use it to focus the review, then read enough current context to validate the affected findings. Inspect the commits affecting that path since the recorded revision as well. When code was removed, inspect the full commits and search the current project, callers, and tests before concluding the behavior disappeared: it may have been renamed, replaced, or moved into another file that should replace or join the page's cited sources. Repeat for every listed file and re-run validation. Keep `index.md` exact, and append a material update entry to `log.md` with source revisions. Only mark a page `verified` after its claims have been checked against its current evidence. Unsupported conclusions stay `needs-review`.
|
||
|
||
## Publication
|
||
|
||
Call `dev_brain_info`, then maintain these pages with the ordinary file tools. Append material updates to `log.md`; `index.md` and `skills.md` are generated and should not be hand-maintained. Finish with `dev_brain_validate`. Structural or provenance errors must be repaired, while broken links are warnings so valid work remains editable instead of being discarded.
|