The .issues flat-file DSL

Inside the core package there is a line-oriented text format that parses into graph nodes. Eleven source files, roughly fifty-five tests across seven test files, three live example files in the project's own graph, and a wired-in repository API. Until this page it had zero prose documentation anywhere — not in a README, not in a brief, not in an architecture document.

What it is

A third way to get nodes into a graph. The other two are the CLI — one command per node — and the Python API. The DSL lets you write a batch of related nodes as plain text in one file, and have them parsed, checked, normalised and turned into nodes.

That matters most for the case the CLI handles worst: sitting down with a page of work in your head and wanting it in the graph. A dozen issues-fs create invocations is a poor way to express one thought. A file is a good one — and, being a file, it diffs, reviews and merges like everything else here.

The eleven source files

issues_fs/issues/issues_file/

The shape of that list is itself informative. Parse, check, normalise, map to schema, construct — five distinct stages with a service each, which is not how anybody builds a throwaway. This is a considered feature that nobody announced.

Where it is wired in

The DSL is not a side tool. It is on Graph__Repository, the same object that loads and saves nodes:

Graph__Repository.issues_files_discover()          # find .issues files in the repo
Graph__Repository.issues_files_load()              # parse and load them
Graph__Repository.issues_files_get_cached_nodes()  # the nodes they produced
Graph__Repository.issues_files_find_node_by_label()
Graph__Repository.issues_files_invalidate_cache()

Two things follow from that surface. There is a cache, with explicit invalidation — so parsed files are held rather than re-read per query. And there is find_node_by_label, which means nodes originating in a .issues file are addressable by the same label scheme as everything else.

The three live files

Issues-FS's own .issues/ directory contains three of them:

The first and third are worth pausing on: the format is being used to track the development of the format. That is the same self-referential move the role ecosystem makes — the tracker tracks its own development — arriving independently in a corner of the codebase nobody documented.

Why it went unnoticed

Four reasons, and together they are a good case study in how a built feature becomes invisible.

1. It has no CLI surface. None of the fourteen commands mentions it. A user exploring the tool through --help will never encounter it.
2. It lives inside the core library, which is the package a user is least likely to read — issues-fs is a dependency of the CLI, not the thing people install directly.
3. It is newest. It postdates every architecture document in the corpus, and no document has been revised since.
4. Its examples are in a dot-directory. The three live files sit in .issues/, which is hidden by default in every file listing anybody runs.

Issues-FS has three agent-operable surfaces — lite markdown, the .issues DSL, and --for-agent JSON. Only the third is discoverable, and only the third has ever been written about.

Using it today

Honestly: read the source first. Specifically:

issues_fs/issues/issues_file/Parser__Issues_File__Line.py    # the grammar
issues_fs/issues/issues_file/Issues_File__Check__Service.py  # what is rejected, and why
tests/…/issues_file/                                          # ~55 tests across 7 files
Issues-FS/.issues/*.issues                                    # three files that work

Then load through the repository API rather than calling the parser directly, so the check and normalise stages run:

repo = Graph__Repository__Factory.create_local_disk(root_path=".issues")
repo.issues_files_discover()
repo.issues_files_load()
node = repo.issues_files_find_node_by_label("Bug-3")

What this section needs next