Spec index

Overview

Gitmoap reads the markdown you already keep in your repository — everything under specs/, docs/, legal/ and blog/ — and turns it into data you can ask questions of: a board of every document with its status, owner and review date; an index of every identifier your writing declares and everyone who cites it; backlinks; a list of links that go nowhere; and a rollup of every unchecked box in the corpus. Push a change and the index moves with it, so which rule says that, who depends on this document and what is still unfinished stop being questions you answer by grepping.

The same pass that builds the index checks the corpus, and it reports on every branch. A merge request whose documents cite a rule nothing declares, link to a file that is not there, claim an id another document already owns, or leave required frontmatter out gets a red check beside its tests, before it lands.

Nothing here writes to your documents. They stay in git, authored in an editor and reviewed as prose in a merge request; the index is a projection of them at one commit, and every operation on this page reads it.

Quick start

Before you start

How it works

What a document turns into

Every document resolves into a document row, a tree of blocks, and three kinds of thing hanging off those blocks. Knowing which is which is most of knowing the API, because nearly every operation here reads one of them and says so in its name.

A document is one markdown file plus its frontmatter. A block is a heading and everything under it until the next heading of the same or shallower level. A record is a typed row inside a block — a table row whose column signature is recognised, or a checkbox item. An identifier is a name your writing declares, and a reference is a citation of one, or a link to a document, a section or a file in the repository. Records, identifiers and references each have their own listing, and none of them is a special case of another: asking the record listing for identifiers returns nothing.

Every one of those rows belongs to a corpus, and the row carries its corpus_id. A corpus is one set of documents with one history: your repository's specs/, docs/, legal/ and blog/ trees are a single corpus, not four, which is why an identifier declared under specs/ and cited under docs/ resolves rather than dangling. A repository's corpus takes the repository's own id, so if you were reading repository_id off a document row before, corpus_id in the same position holds the same value.

The distinction earns its keep as soon as something other than a repository has documents — a wiki, whose pages are markdown at a commit in a place that is not a repository, and which gets the same document rows, the same table of contents, the same backlinks and the same findings from the same index.

The heading number is stored and returned, and nothing is keyed on it: a block is identified by its normalised name with the number stripped, so renumbering ## 6. Business rules to ## 7. Business rules leaves it the same section in the index, with the same records and the same identifiers. Its anchor is a different matter — an anchor is slugged from the whole heading, number included, so renumbering does change it and does break a link built from the old one. That makes a cross-reference written as a bare section number the fragile kind: renumber, and it quietly lands on a different section, or on none — and only the second of those is caught, as a GSF_DANGLING_SECTION_REF warning whose message says a number is a position and positions drift. Link to a section by its anchor, or cite an identifier the section declares.

What a document declares

Frontmatter is a YAML mapping delimited by --- as the very first line of the file. Every key is optional except the three that a conformance claim requires.

An unrecognised key is kept and reported as a warning rather than dropped, so a typo produces a finding instead of quietly deleting half your metadata. The two date keys are stricter: a value that is not a calendar date is an error finding and the value itself is dropped, because a date that is not a date cannot be stored as one — the rest of the document still indexes, and the finding names the file and the line. An all-capitals placeholder such as YYYY-MM-DD is read as a template rather than a mistake and produces nothing.

The identity is the id, not the path

Documents are listed, addressed and linked by id. Move a file into a subdirectory and keep its id and nothing breaks: the path is an attribute, and every identifier it declares, every backlink into it and every reference out of it stays where it was. Change the id and you have described a different document — the old one becomes an orphan and the new one starts empty.

A document that declares no id falls back to its path below specs/, docs/, legal/ or blog/ with the extension dropped and the slashes turned into hyphens, so specs/issues/roadmap.md is issues-roadmap and a folder's README.md takes the folder's own name. That fallback is a path, which means moving such a file is a rename. Declaring an id is what buys you the freedom to move it.

Deleting a file does not delete its row. The document is marked orphaned and keeps its identity, so an old link resolves to this moved rather than to nothing. Orphaned documents are left out of listings unless you ask for them, and the identifiers they declared are retained — an identifier is never released, or a rename performed as a delete and a re-add would silently free every name the document owned.

Every branch is checked; the default branch is what you read

A push that changes no markdown under those four directories costs one file-list comparison and stops there, so the overwhelming majority of pushes do no work at all. A push that does change one parses the files that moved, resolves them against everything already indexed, and posts a gitmoap/specs commit status: green with the counts, red with the first failure and its file and line.

That check is the point of validating branches. A dangling identifier citation is invisible in a diff and nobody runs a linter over prose, so the feedback arrives where a reviewer is already looking.

A finding is about a document somebody edited; a dangling link is about the corpus

The two reports look similar and are not the same thing, and the difference will surprise you exactly once.

Findings come from parsing. They belong to the document that was read, and severity = error is what turns the commit status red.

Unresolved references come from resolution across the whole corpus. When you retire an identifier or rename a document, every citation of it anywhere becomes unresolved immediately and shows up in the dangling report — but the documents holding those citations were not re-read, so their own checks stay green until something edits them. That is deliberate: attributing a diagnostic to a file whose bytes nobody looked at would be a worse lie than the gap. Watch the dangling report after a rename; do not wait for a red check that belongs to someone else's next commit.

When the index is behind

Every rollup carries the commit it describes and whether anything is behind. A document is marked stale for one reason: a corpus over the file bound, walked as far as the bound, leaves everything past it holding whatever the previous pass recorded. That only arises on a pass that walks the whole tree — the push that creates a branch, or one whose diff against the commit before it cannot be worked out — because an ordinary push reads exactly the files that changed and knows the rest are unchanged. Staleness is recorded rather than inferred, and a later pass finishes the job.

How to

Check whether your corpus is indexed and current

Start here whenever an answer looks wrong. The rollup gives you the commit the index was built from, when that happened, whether anything is behind, how many documents are orphaned, how many references dangle, and the counts by kind, status, posture and severity — enough to tell "there are no findings" apart from "nothing has been indexed".

An absent commit means nothing has ever been indexed in this repository — push a change to a markdown file under specs/, docs/, legal/ or blog/ on the default branch and it will be.

Browse the documents in a repository

The document listing is the board you would otherwise maintain by hand: every file with its title, kind, status, review date, owner, block and record counts, and how many findings it carries. It is ordered by document id and paged with a cursor, so a page boundary is stable while you walk it.

Combine the filters to answer the question you actually have. ?status=implemented&stale=true finds documents claiming to be finished that the last pass never reached. ?posture=untyped finds the files that opted out of checking. ?search=quota matches on title, summary or id. ?include_orphaned=true brings back the documents whose files are gone, which is how you find where something moved to.

Open one document

One call gets you the document's metadata, its full heading outline and up to a hundred of its findings. It does not include the prose — that is a separate read, so that a table of contents does not cost a document. A document carrying more than a hundred findings is unusual and worth reading through the findings listing instead, which pages.

Build a table of contents

When you want the outline and nothing else — a navigation sidebar, a link-checking script, a jump list — read the blocks on their own. Each block carries its level, its heading verbatim, its normalised name, its resolved kind, its line range, its first paragraph as a summary, and its anchor.

Use the anchor, never the heading number. The anchor is what a git host generates for the same heading, so a link built from it works in the web app and in a raw markdown view of the same file.

Read a document's markdown

The content read returns the file's prose with its frontmatter stripped, at the commit the index was built from — not at the branch tip. That pinning is a correctness property rather than a caching choice: records are addressed by their position in the document as it was parsed, so prose fetched at any other commit would put a highlight on the wrong table with nothing to notice.

The response carries the commit it came from and an entity tag, so a client that already has the document gets a 304 and a header exchange rather than the file. To read a document at any other ref, read the blob instead: that is the code browser's job, and it returns the file exactly as it is in git, frontmatter included.

Find every identifier the corpus declares

If your writing names things — rules, tenets, invariants, decision records — this is the index that makes them real. Every declaration comes back with its family, its title, the document and line that declares it, whether it is tombstoned, and how many times the corpus cites it. A rule with zero citations is visible as a rule nobody cites.

Filter by family with ?id_kind=rule, by state with ?tombstoned=true to see what has been retired or moved, and by substring with ?q=AUTH to find every identifier whose name contains it.

Look up one identifier and everyone who cites it

Ask for an identifier by its family and its exact text. You get its title, where it is declared, whether it is tombstoned, its typed body where the family has one — a rule parses into its why, its how and what enforces it — and the list of citations with a document and line each.

The citation list is capped at 200 and says so with a flag when it is cut, because the identifier everybody cites is exactly the one whose page must stay bounded. Page the remainder through the reference listing filtered by target identifier.

A 404 here is itself a useful answer: it means nothing in the corpus declares that identifier, which is the mechanical form of is this rule real?

Find broken links, and everything that links here

Every cross-reference the corpus makes is stored with its raw text, its line, the form it took, and whether it resolved. That one table answers three different questions depending on how you filter it.

• ?resolved=false is the dangling report — every link, path, section reference and identifier citation that points at nothing.
• ?target_doc_id=<id> is backlinks — what links to this document.
• ?target_id=<identifier> is who cites this rule, and the full list behind a truncated identifier page.

?ref_kind= narrows to one form: document, section, anchor, identifier, code or operation.

Read the findings from the last check

Findings are the check's output, kept and queryable rather than scrolled past in a log. Each one carries a code, a severity, a message and — where the problem has a location — a line. Filter by ?severity=error to see only what turns the check red, by ?code= to work through one class at a time, or by ?doc_id= to see one file's.

Query typed rows across every document

This is the operation that pays for the whole feature. Tables in your documents that share a column signature are recognised as records of a kind, and one filtered read returns rows of that kind from every document at once. Every error status the corpus documents, every invariant, every parameter table, every unchecked box — the same call with a different kind.

?kind=errors&q=409 gets every documented 409 across the corpus. ?kind=checkbox&doc_id=<id> gets one document's checklist, in order. ?block_kind= restricts to rows inside a section of a given kind, so the parameter tables in Endpoints sections is expressible without naming a document.

Each row comes back with its recognised slots in core, everything else the table carried in extra, its position, and whether the row was struck through.

Pull the unfinished work out of the corpus

Every unchecked checkbox in every document, with its text, its document, its enclosing section and its line. A per-file convention becomes a backlog you can read in one place, and the same list narrowed with ?doc_id= is one document's remaining work.

Checked items are not returned — this list is what is outstanding, not a history of what was done.

List the endpoints your specs declare

Where a heading names an operation as a backticked method and path, that declaration is extracted: method, path, the document and anchor that declare it, and the section's summary. It is the API surface as written down, which is what you need to compare against the API you actually serve.

The list says nothing about whether an endpoint is served. Whether a given path exists in a running service is a fact about your repository, not about your prose, and Gitmoap does not guess at it.

See which documents depend on which

The graph is built from references that actually resolved, so it describes what your documents really cite rather than what they claim. Alongside it you get the depends_on each document declares, returned separately and never merged in — the disagreement between the two is the output. A declared dependency with no reference behind it is stale or aspirational; a document cited forty times and declared nowhere is a real dependency nobody wrote down.

Name a root to walk outward from one document, or omit it for the whole graph. depth clamps to six hops and defaults to six, so asking for forty gets you six rather than an error, and the response is capped at 500 nodes with a flag saying whether the cap was hit — past it you are looking at a sample in the shape of a graph, which is worth knowing before you draw conclusions from it.

List every document across a group

The group rollup spans every repository in a group's subtree, including nested groups, and returns the same document rows with the repository each belongs to. It takes the same filters as the repository listing, so every draft document in the whole organisation, sorted and paged is one call.

Rows you cannot see are removed inside the query rather than after it, so a page is never short because it was filtered, and the cursor stays honest.

Check a whole group's corpus at a glance

The estate rollup: how many repositories in the subtree have a corpus at all, the total documents, records and identifiers, how many documents are behind, and findings by severity. It is the number to put on a dashboard, and the one to watch after a large refactor.

Every count folds the same visibility rule the listing does. Withholding rows while publishing a total would still leak the existence of a private repository, so the totals are the totals you can see.

Make a broken corpus fail a merge request

There is nothing to switch on. Every push to a branch and every merge that touches the corpus is checked, and the result is posted to the commit as a status named gitmoap/specs — green with the counts, red with the first error, its file and its line. It appears in the merge request's checks list beside your build and your tests.

Findings of severity error are what turn it red; warnings are recorded, stay queryable, and leave the check green. A document that could not be parsed at all also turns it red, naming its own file. The status reports — it is a signal beside the merge request's other checks rather than a gate that refuses a merge on its own, so treat a red one the way your team treats a red build.

Reference

The vocabularies below are what the filters on these operations accept. Everything else in this section — paths, parameters, shapes, scopes and errors — is generated from the API itself.

Document statuses. draft, review, approved, implemented, partial, superseded, living, none. partial and living exist because real corpora need them: work that is half shipped, and documents that are never finished by design.

Postures. declared for a document carrying gsf: 1, whose frontmatter, identifiers, blocks and references are all checked. untyped for one that makes no claim: parsed, indexed, searchable, linkable, and never a finding. There is no third posture and no partial mode.

Identifier families. rule, tenet, principle, invariant, dogfooding and generic. Which shapes declare which family comes from the vocabulary reading the document; under the default vocabulary a heading that begins with an upper-case hyphenated token followed by an em dash — RFC-0012 — Retry policy — declares a generic identifier, and citations of it anywhere in the corpus resolve to it. Principles are document-scoped, since P1 means a different thing in every document that has one; every other family is unique across the whole corpus, which is what makes a duplicate declaration an error rather than a coincidence.

Reference forms. document, section, anchor, identifier, code and operation. A code reference is a backticked repository path — `app/server.ts` — checked against the tree at the indexed commit. A path that names another commit says so on the line with a marker: *(planned)* for one a later commit will carry, *(removed)* for one an earlier one did, *(moved)*, *(example)* for a path in somebody else's repository, and *(generated)* for a build artifact no commit contains. A marked path is still indexed and still appears in the graph; the marker suppresses the finding, not the reference. A backticked path whose first segment names no top-level entry of your repository is read as ordinary prose rather than as a reference at all, which is what keeps a shell fragment or a path in somebody else's project out of the dangling report without anyone marking it.

Record kinds. Twenty-eight named table shapes, plus checkbox for checklist items and unclassified for a table whose signature nothing claims. Under the default vocabulary three universal shapes are recognised — a section index, a parameter table (name, type, description, with optional required and default), and a two-column key/value table — and everything else is unclassified, which is a correct description rather than a defect. Richer vocabularies recognise more.

Finding codes. The ones you will meet. Severity error turns the check red; warning leaves it green:

The last three are the ones that behave differently, and it is worth knowing before you go looking. A refusal means the document could not be read at all, so it contributes no blocks, no records, no identifiers and no finding row — it reddens the check with its own file name and message, and the findings listing stays empty for it. A file that is not valid UTF-8 is refused the same way, as GSF_NOT_UTF8. Those four are the whole of the refusal set; everything above them is a finding on a document that still parses and still indexes. refusal is not a severity you can filter on, either: ?severity= takes error, warning or info and refuses anything else, because a refusal never produced a row to filter.

A red check does not hold the index back. A document with an error finding is still written, because the index is a projection of what the corpus says — including when what it says is wrong — and one refused file does not stop the others in the same push from indexing.

Limits

None of these operations creates anything, and none of them counts against a quota — no plan changes what you can read here. The bounds are on size, and they exist so that one enormous document cannot make an index unbuildable.

Two bounds refuse. A single markdown file over 512 KB is not indexed at all — the check goes red naming that file, and because a refused document produces no finding row, the red status is the only place you will see it. Past 1 MB the file is not read at all, so it does not even get that far: a document that grows over a megabyte drops out of the index the way a deleted one does, and is marked orphaned. Split the file well before either bound, or accept that it is browsable only in the code browser. A whole-tree pass reads at most 2,000 files, and every indexed document it did not reach is marked as behind for a later pass to finish; the truncation is reported rather than left for you to infer from a count.

Every other bound truncates, because a document with a 600-row table is unusual rather than invalid, and dropping it from the index over a formatting choice would be worse than keeping the first 512 rows. Four of those truncations record a GSF_TRUNCATED warning against the document so you find out; three cut quietly, and are worth knowing about precisely because nothing will tell you.

And the bounds on what a single response returns:

Troubleshooting

FAQ

Related