Vault Project Yaml - alexherrero/agentm GitHub Wiki

Vault project.yaml reference

Note

Status: implemented โ€” shipped by tasks/176-converge-the-vault-layout (step 5). Every one of the 12 live vault projects carries a project.yaml; check-project-yaml reads 0 findings across 12 of 12 as of 2026-09-25. Two optional keys came after it: former_names (task 186) and bare_issue_floor (task 187).

Every vault project's root carries a project.yaml โ€” the grounding config a session reads to tell which project it is in and what that project touches, without parsing prose. It is one of the five files the project root is locked to; see Memory daemon reference ยง The project root locks to five files.

โšก Quick Reference

Field Type Required Meaning
slug string yes The project's directory name. check-project-yaml fails the file when this doesn't match (scripts/check-project-yaml.py:83-84).
title string yes The project's human-readable name; must be non-empty (:85-86).
status string yes One of queued, active, parked, done, dropped (:57, :87-88).
repositories list of owner/repo yes The GitHub repos this project touches. May be empty (:58, :89-96).
code_paths list of ~/โ€ฆ strings yes Home-relative paths into those repos, for wherever the code actually lives. May be empty (:97-104).
board mapping (owner, number) no The GitHub Project this project syncs to, when one exists โ€” exactly owner (string) and a positive number, nothing else (:105-111).
sensitivity string no One lowercase word, e.g. personal-financial (used by the home project) โ€” flags data the operator wants handled carefully (:59, :112-113).
former_names list of owner/repo no The names a renamed repository used to have, for a project that lists exactly one repository (:114-123). The entity builder folds each old name into the current repository's page, so a note that still cites the old name counts toward it (task 186).
bare_issue_floor positive whole number no Where the repository's issue numbers start, for a project that lists at least one repository (:124-129). A bare #NN below it stays unqualified, issue:#NN; see Bare issue floor (task 187).
Where's the template? โ€” โ€” standards/templates/project.yaml โ€” seeds every new project's copy, minus slug. standards/templates/ is in recall_exempt_areas, so the template is never indexed or served by recall; it's a shape to copy, never content to surface.
What checks it? โ€” โ€” check-project-yaml โ€” see CI gates reference.
Related pages โ€” โ€” Memory daemon reference, CI gates reference, Project config reference (a different file โ€” the harness's .harness/project.json)

Schema

project.yaml parses as a YAML mapping. Any key outside the required and optional sets below is a finding (scripts/check-project-yaml.py:80-82) โ€” a typo in a key name is caught rather than silently ignored.

slug: example-project
title: Example Project
status: active
repositories:
  - owner/repo
code_paths:
  - ~/code/repo
board:
  owner: owner
  number: 2
sensitivity: personal-financial
former_names:
  - owner/old-repo-name
bare_issue_floor: 48

standards/templates/project.yaml is checked the same way, except it carries no slug โ€” the one field a template can't have, since it names the directory the template itself isn't in (scripts/check-project-yaml.py:76).

Bare issue floor

A repository whose roadmap numbered its items in the same range as its first GitHub issues makes a bare #15 in an old note mean either one. bare_issue_floor says where the issues start: set it one above the roadmap's last item, so 48 for a roadmap that ran to item 47. Below the floor the extractor leaves a bare number unqualified, as issue:#NN. The note is still found by it in search, but no issue page is built from it.

Written as Below the floor At or above it
#NN, (#NN) stays issue:#NN qualifies to the note's repository
crickets #NN (a repository's short name first) stays issue:#NN qualifies to that repository
PR #NN, issue #NN, pull request #NN qualifies qualifies
owner/repo#NN, a GitHub issue or pull request address qualifies qualifies

The floor belongs to a repository, not to a note. A project's floor applies to each repository it lists, a repository two projects list takes the higher of the two floors, and one repository's floor says nothing about another's. The daemon's reader (projectbind.IssueFloors, daemon/internal/projectbind/projectbind.go:190) gives no floor for a value that is not a positive whole number. The gate is stricter: it also refuses a bool or a quoted number, and a floor on a project that lists no repository.

The floors are part of the index's recorded extractor version (extractorVersion, daemon/internal/index/entityreextract.go:35). Setting, raising or removing a floor therefore re-derives every indexed note's entity rows on the daemon's next open, with no reindex. How the extractor reads a reference is in Memory daemon reference ยง Entities, and the pages built from them.

Related

  • Memory daemon reference โ€” the space table and the door's five-file project-root lock this schema fits into.
  • CI gates reference โ€” the check-project-yaml gate that validates every project's copy.
  • Project config reference โ€” the harness's own .harness/project.json. A sibling concept, not the same file: that one is per-repo enablement config; this one is per-vault-project grounding config.
โš ๏ธ **GitHub.com Fallback** โš ๏ธ