PROP-043 — The facts markup: the inline status grammar and its IR

3.1 The <status> element

14One XML-shaped element, embedded in Markdown (and, later, native in XML documents — the frontend duality of PROP-035 §5):

<status stage="impl" state="work"/>                       — point marker
<status stage="test" state="plan">wrapped text</status>   — fragment wrapper

• 16A point marker MUST be self-closing (/>). An unclosed <status …> point form is not well-formed XML and is a check error.
• A fragment wrapper is the paired form around text inside a paragraph.
• Inside fenced code blocks, inline code spans, and URLs the element and the shorthand (§3.7) are not recognized — the scanner is fence-aware.

17Decision — element name status, not progress.

• 18Why: <progress> is an HTML5 element: GitHub-class sanitizers strip it, and html:true renderers (VS Code preview) draw a literal progress-bar widget mid-spec. status is not an HTML element and renders inert.
• Considered and rejected: progress (HTML collision), vp/prg (unreadable), HTML comments (invisible in raw reading, defeating the point).
• Revisit when: the XML storage frontend lands and element naming is re-grounded in a schema.

3.2 Attributes

• 20Vocabularies are closed. Any value outside the tables is a check error with a nearest-legal-value hint (typos like rewrok die in CI, not in review).
• New values enter only by amendment to this section.

21Multiple markers on one node: at most one status marker (stage/state), any number of action markers — a unit may legitimately need remove+actionstage="doc" and continue+actionstage="test" at once.

3.3 Stages

• 22idea — a thought worth keeping, not yet specified.
• spec — being specified / specified.
• impl — being implemented / implemented.
• test — being tested / tested.
• doc — being documented / documented.
• freeze — freezing as a deliberate process: freeze/plan (we intend to freeze), freeze/work (final checks), freeze/done (frozen).
• unknown — looked at, not understood; explicit triage demand. Distinct from no marker ("nobody looked yet").

23Decision — freeze, not a terminal done stage.

• 24Why: freezing is a process (planned, executed, and later reversed — unfreeze is an ordinary marker change back to spec/idea/impl; history lives in git). A done stage collided semantically with the done state.
• Considered and rejected: stage="done" (ambiguous against state="done"); a boolean frozen flag (hides the process).
• Revisit when: never expected; the cycle-of-improvement premise is core.

• 25The stage order is fixed for aggregation: idea < spec < impl < test < doc < freeze; unknown sits outside the order and compares below everything.
• The order is a sort key for rollup, not a process law: test and doc interleave in reality, and falling back (impl → spec, spec → idea) is legal and expressed by simply changing the marker.

3.4 States

• 26plan — intended, not started.
• work — in progress.
• done — done for that stage.
• hold — deliberately parked (neither worked nor discarded).
• void — the unit no longer asserts anything. Named for a void contract — without effect — deliberately not the programming sense of "still works, discouraged". The unit was either split into heirs and left as a pointer to them, or cancelled with no replacement; its text survives only so its name is not reused and inbound links do not break. It is neither work outstanding nor work completed but no claim at all, and §3.10 sorts it accordingly. Marking one is the author's judgment about their own corpus — nothing derives it.

3.5 Actions

• 27continue — unfinished; carry on (spawns tasks in the campaign).
• drift — diverged from reality; reconcile. Operationally bound to the sync-from-code flow when the code is right and the spec is stale: the marker names the problem, that flow is the procedure.
• rework — exists but bad; redo (pairs with the feature-flag disable path).
• remove — bad or abandoned; delete (or demote to idea/hold archive).

28actionstage narrows the target: action="remove" actionstage="doc" = "the documentation of this is to be removed", while stage keeps describing the unit itself.

3.6 Audience

• 29For whom this promise must eventually be told: user (writes specs in their own project, installs dependencies; never opens the package internals), author (builds packages; wants depth), dev (vibevm's own developers — the spec tree itself serves them; the default), and — admitted 2026-09-11 by PROP-057 §14 — agent (a session reading on a user's behalf: the boot snippet, a skill's instructions, the machine-facing corpus; text for it obeys the agent-text laws of that PROP — a token budget, no narration, never in a boot prefix). The grammar itself knows nothing of lanes; where such text may appear is PROP-057's rule, not this vocabulary's.
• Primary use: actionstage="doc" markers with an audience are the obligations of the documentation — the promises a page for that audience must cite. vibe progress report --view doc --audience user|author|dev|agent lists them; it is the source of the coverage gate vibe doc check --coverage (PROP-057 §14, the ratchet PROP-047 ##DOC-COVERAGE-RATCHET names), never a table of contents — navigation is derived from the page manifest (amended 2026-09-11; the earlier wording fed the two guides' tables of contents).

3.7 Shorthand

30@status:<stage>/<state> and @status:<stage> are macro-equivalents of a point marker. The legacy spellings @<stage>/<state> and @<stage> mean exactly the same and are still read, so a document written before the qualified form keeps parsing.

• 31@status:test/plan ⇒ <status stage="test" state="plan"/>
• @status:impl ⇒ <status stage="impl" state="work"/> — bare shorthand defaults to state="work", with exactly one exception: @status:unknown ⇒ state="hold". (@status:freeze ⇒ freeze/work: "freezing now".)

• 32Why the key is named. These documents share the @ space with foreign annotation grammars — JSDoc, TypeScript directives, npm scopes, Java annotations, and plain x@y addresses. Without a key the reader must tell its own tokens from those by a vocabulary of stages and states, which answers "is this mine?" with a dictionary lookup instead of with the token's own shape.
• Disambiguation against the @spec:// directive grammar (in-place spec citations) applies to the legacy form only: after @spec the scanner looks ahead — :// follows ⇒ foreign directive, not ours; /<state>, whitespace, or end-of-token follows ⇒ shorthand. The qualified form needs no lookahead: @status:spec/done cannot be confused with @spec://…, because the key is stated before the value.
• A shorthand is recognized only as a standalone token at the start or end of a paragraph's text, never mid-sentence, never inside code or links.

3.8 Placement

33Six granularities, one rule each — and no ambiguous positions:

1. 34Document — marker in the preamble, before the first heading. Pilot amendment (2026-07-24): a document that opens with its heading (the standard shape of this repo's specs) has no preamble; there, the standalone marker immediately after that first heading is the document marker, not a section marker.
2. Section — marker on its own line immediately after the heading line (for any heading other than a preamble-less file's first one, per the amendment above). This is the only legal standalone position inside a body.
3. Paragraph — marker inside the paragraph's own text: the first token (right after the newlines, or right after the paragraph's @fact:<ID> anchor) or the last token (right before them).
4. List item (fact amendment, 2026-07-24 — owner-directed) — every item of a bulleted or numbered list is a unit of its own, at every nesting level. Its marker — shorthand or XML form alike — sits inside the item's own text: the first or last token of the item (before any nested sub-items, which carry their own markers).

• 35Fact anchors — the anchored-when-marked law (owner, 2026-07-24; spelling amended 2026-08-06). A stable fact address is written @fact:<ID> as the first token of a paragraph or list item. The legacy spelling ##<ID> means the same and is still read.
• Why the key is named. ##<ID> was never a heading — an ATX heading requires a space after the hashes, and this markup is written closed up — but it reads like one to a markdown linter, to a parser outside CommonMark, and to the eye. @fact: states what the token is instead of relying on a reader knowing what it is not.
• A fenced block is an example, not an assertion (owner, 2026-08-06). By default nobody is asked to believe what a fence says and no agent is asked to run it. Marking the fact @fact/code:<ID> makes the fence part of that fact's body: the fact then has an address, a verdict, and it comes due for re-judgement when the block's text moves.
• Why the type exists. A fence carries no anchor of its own and cannot be given one — it is a payload, copied out and pasted elsewhere, and an anchor written inside would travel with the copy. Measured over this corpus: 372 fenced blocks carry zero facts while all 7255 text blocks carry theirs, so a claim inside a fence belonged to nobody, could not be judged, and could not be made stale. Two false statements survived exactly that way in one week.
• The known type set is code, and that is a measurement. Fences are the only block kind falling outside fact bodies: the corpus holds no images at all, and 891 of 908 table rows and 84 of 96 block quotes already sit inside a fact. A type naming a block kind that is already covered would address nothing.
• An unknown type is a check error, as are a typed anchor that is not its block's last fact and one with no matching block below it. Ignoring an unimplemented type would let the grammar promise what it cannot do, and the author would learn years later that nothing read it.
• <ID> is [A-Za-z][A-Za-z0-9_-]*; the unit is then addressable as spec://…/<doc>#<ID>, sharing one address space with the heading {#anchor}s — a duplicate across both forms is a check error. The address is unchanged by the spelling: it names the id, never the opener.
• Every unit that carries a status marker — paragraph or list item — MUST also carry a @fact:<ID> anchor; a marked, anchor-less unit is a check error.
• The marker may stand immediately after the anchor (1. ##RULE-001 rule text @freeze/done — the owner's canonical example shape) or as the unit's last token.

• 36Decision — two anchor-id registers (owner ruling, 2026-07-24). @fact:UPPER-SLUG names a normative fact (a law, rule, carrier, changelog entry — content with binding weight); @fact:kebab-case names a service unit (status lines, lead-ins, connective prose).
• Why: the register itself carries the normativity signal at zero syntax cost; ratified from the PROP-029 re-pilot mix reviewed in session.
• Considered and rejected: single UPPER register (service units become shouty; the signal is lost); single kebab register (normative facts stop standing out; the re-pilot would need re-anchoring).
• Revisit when: the post-campaign fold (§3.9) shows the mixed registers confusing report consumers or check tooling.

• 37Table addressing (proposed 2026-07-24, this session — same syntax, no new grammar). A @fact:<ID> as the first token of the first cell of a body row addresses that row (| ##ROW-PKGREF pkgref | … |); in any other cell it addresses that cell; the whole table is addressed by the anchor of its lead paragraph (the target set: ##TBL-MIRRORS) or its section.
• Positional schemes (r2c3) are rejected — a row shuffle breaks them; a minted id travels with its row.
• Cells stay exempt from the anchored-when-marked obligation (mint ids only where something cites them); a table that is really a list of facts is deconstructed into an anchored list instead.
• Table cell (fact amendment, 2026-07-24) — every non-empty body cell of a table is a unit of its own; its marker sits inside the cell's text, first or last token. Header rows and the delimiter row are structure, not units. A table whose rows are really a list of facts is better deconstructed into a list (§3.9); cell markup is for tables whose tabular shape is essential.
• Fragment — paired <status>…</status> around text within a paragraph, list item, or cell — the form for an inline fact that cannot be pulled out of its sentence.

• 38A standalone marker between two paragraphs is a check error — there is no "nearest paragraph" heuristic.
• A section's span follows the owner-fixed IR rule (PROP-035 §5): from its heading to the next heading of the same or higher level.

3.9 The granularity doctrine — facts are the campaign grain

• 39Anchored units are the maintenance granularity. Between campaigns, markup lives on {#anchor}-ed units; reports cite spec://…#anchor; this is the stable, refactor-proof form.
• Facts are the campaign granularity (fact amendment, 2026-07-24 — owner-directed; supersedes the paragraph grain of the original text). An actualization campaign demands verbatim exhaustiveness at the grain of individual facts, because a paragraph routinely carries several and an LLM pass silently skips the inner ones. Operationally:
• every paragraph, list item, and non-empty table body cell carries its own marker — these are the countable units the exhaustive counter enforces;
• a paragraph that carries more than one fact is deconstructed — rewritten, sense-preserving and wording-preserving, into a bulleted or numbered list with one fact per item, each item marked. Most prose is expected to become lists; a paragraph stays prose only when it truly carries one fact (or none — connective tissue);
• a fact that cannot leave its sentence (an inline clause, an enumeration inside one sentence that resists splitting) is wrapped as a fragment: <status …>the fact</status>;
• campaign passes still add missing {#anchor}s; deconstruction changes form only — semantic edits belong to the drift-correction stage, never to markup passes.
• After a campaign, density is folded back: a section whose units agree collapses to one unit marker (check verifies the fold is lossless); mixed sections stay fact-marked.

3.10 Inheritance and rollup

• 40Downward (defaulting): a node's marker covers unmarked descendants.
• Upward (aggregation): an unmarked node's computed status is the worst-of its children per the §3.3 order (unknown wins the bottom).
• void is the one value outside the (stage, state) order: it sorts above every other pair regardless of stage, so worst-of never returns it while any live unit remains. worst-of {spec/void, impl/plan} is impl/plan — the live part governs and the tombstone's stage does not drag the document back to spec; worst-of {done, void} is done. A document whose every unit is void is void, which falls out of the same rule rather than being special-cased. This is a property of the pair: giving void the top state slot within its stage would leave @spec/void governing by stage anyway, which is why two of the three options originally proposed for it could not work.
• An explicit marker always beats both directions. Reports show explicit and computed separately — a divergence is information, not noise.

3.11 Terminal artifact obligations

41Decision (owner, 2026-09-09): terminality is independent of status. stage/state continues to answer where a fact stands now, and done continues to mean done only for that stage. An addressable fact may separately declare the artifact kinds whose satisfaction closes the whole fact. No stage is a mandatory successor of another, and no fact is forced toward source-code implementation merely because its specification is complete.

42The Markdown form is exactly one qualified trailing annotation @requires:<kind>[,<kind>…], immediately before the fact's final status shorthand admitted by §3.7 (qualified full/bare or legacy full/bare), or final <status …/> point marker. @requires itself has no legacy bare spelling. The XML-dialect equivalent is a requires="<kind>[,<kind>…]" attribute on the named or generic fact element, beside status; it is never an attribute of the standalone document/section <status> element. Both forms lower to one fact-owned semantic set.

@fact:PROTOCOL The protocol text is the delivered artifact. @requires:specification @status:spec/done

@fact:PARSER The parser implements and proves the grammar. @requires:implementation,verification @status:test/done

• 44A requirements annotation belongs only to an explicitly addressed fact. Paragraphs, list items, quotes and table cells may carry it; a table cell loses its usual anchor exemption when it does. A fragment, an unaddressed unit, a document marker and a section marker cannot carry requirements. @fact/code: may carry them normally; its bound fence remains part of the same fact body.
• The complete trailing cluster is @requires:… then the status marker, with only whitespace between them and nothing after the status. A second contiguous @requires token in that trailing cluster, an empty member, a leading or trailing comma, or a trailing requirement with no final status is a parse error rather than a best-effort attachment. An occurrence separated from the final status by ordinary prose is not in the cluster and remains prose.
• Fenced code, inline code and link destinations remain opaque. Any look-alike outside the exact trailing cluster remains ordinary Markdown even when its comma-separated value happens to use legal artifact names; only the cluster is grammar. The parser does not reserve every occurrence of the English word requires.
• Requirements are a non-empty unordered set. The IR stores them in the fixed vocabulary order and every backend emits that canonical order. Authored duplicates are an error, not silently meaningful repetition. Changing presence, membership or spelling changes the fact content identity and therefore makes prior campaign verdicts due for re-judgement.
• Absent requirements mean unclassified terminal contract, never an empty set and never vacuous success. Existing facts therefore retain their exact status and acquire no terminal claim. An explicitly empty set is invalid; a live fact that requires nothing uses a self-carried artifact kind, while a void fact carries no requirements because it asserts no claim; state=void plus a requirements annotation is a parse/check error, not an ordinary pending fact.