E.8:4.1.1 - Heading & ID discipline (human tooling + retrieval)
FPF is often consumed through full‑text search and retrieval (RAG). A reader or an LLM may see a subsection without its parent headings. Headings must therefore be self‑identifying.
The following grammar governs Markdown publication forms authored under this E.8 edition. Its heading levels, separator and sentinel spellings are necessary subject conditions under E.5.1; they do not make the represented conceptual objects depend on Markdown.
Markdown without raw HTML. Markdown publications in FPF Library, and other Markdown publications governed by this profile, MUST NOT contain raw HTML elements or comments, including empty anchors and HTML used for layout. Use Markdown headings, links, tables and images, with the mathematical notation declared by the publication.
Show literal HTML discussed by the text inside code spans or fenced code blocks. Such code, mathematical angle brackets and Markdown autolinks are not raw HTML markup.
The restriction covers complete publications, including framework editions, non-framework References, Readmes and other Library entry material. Preserve information when converting an existing presentation; removing a tag does not justify removing the content it presents.
H-1 (Heading shape). Every pattern heading and every subsection heading inside a pattern SHALL follow:
<hashes> <FullId> - <Title> (optional note of non‑normativity)
Exception. The Footer marker is a sentinel heading and is governed by H-9, not by the standard <FullId> - <Title> shape.
H-2 (Heading separator). The canonical separator is ASCII space-hyphen-space, as in <FullId> - <Title>.
Previously authored headings may use Unicode separators, as in <FullId> – <Title> or <FullId> — <Title>. Tooling SHOULD treat these as migration candidates, and authors SHOULD migrate touched headings to the ASCII separator in H-2.
H-3 (FullId). FullId is the complete address used by this heading grammar.
For a pattern heading it is the PatternID (e.g., A.2, E.10.D1).
For headings inside a pattern, append dot-separated ordinal section numbers after the colon (:) (e.g., A.2:4.4, E.10.D2:3).
Exception: the Footer marker uses the reserved sentinel token :End as defined in H-9.
The colon (:) is reserved for section paths and MUST NOT appear in PatternIDs.
Retained published addresses. When repairing an already published heading, preserve its established address and the contribution it denotes. An existing non-ordinal address is a compatibility exception, not a form for new addresses. Establish that exception from the exact earlier publication and its target; a permissive parser match does not establish it.
An absent address receives a new ordinal address chosen by the source author. A local component, clause or extension name remains its own declaration under H-10; it does not by itself supply the missing subsection address.
PatternID segments may be numeric or mnemonic. When the surrounding text identifies the framework, the complete PatternID identifies one pattern in that framework. The shape of its segments does not by itself state the pattern’s title, meaning, Part, publication position, dependency, Method relation, or use order. A mnemonic segment may help recognition but does not define the pattern.
Whether a PatternID stays with a changed pattern is an authoring decision, not a grammar decision. For a DPF, use E.4.DPF. Use E.11.PFP to show current publication position separately. When the surrounding text does not already identify the framework, name the framework together with the PatternID. Add the edition when the reference must select the body published in one edition.
H-4 (Ordinals). Ordinals in section paths SHOULD track the canonical template numbering (1 = Problem frame, …, 13 = Footer marker) to maximise cross‑pattern comparability. During refactors or in previously authored patterns, ordinals MAY be local. In that case, the canonical section title at the start of <Title> is the semantic key. Readers and tools MUST NOT infer section semantics from the ordinal alone.
Architectural Rationale is the preferred title of the Rationale function. Rationale remains an accepted alias. Both identify one canonical content section, so a pattern carries exactly one of them.
When an existing heading is retitled, repair title-dependent links and direct consumers under E.8:4.1.2; retaining its ordinal alone does not preserve a Markdown return.
Keep addresses through change. Inserting, moving or retitling a subsection does not assign its address to a different contribution. Keep existing addresses when their contributions continue. Give a new contribution an unused address. Do not renumber unaffected subsections to restore display order or reuse a retired address for different content. For a genuine replacement, split or merge, decide which contribution continues and state which returns have changed or remain unresolved.
For example, when a new explanation is inserted between existing sections 4.1 and 4.2, an available 4.3 can name the insertion while 4.2 still names its former explanation.
Before publication, compare the earlier and revised targets, preserve the earlier carrier fragments through compatibility facilities permitted by the selected publication form and supported by the access route, and update maintained direct links. Test duplicate-title suffixes and alias collisions as well as visible FullIds.
A saved link must return to its intended contribution or expose that the return is unresolved; reaching a different heading silently is a failure. The author judges the contribution. A link checker can verify the declared correspondence.
Note: the Footer marker is exempt from ordinal encoding. It uses the reserved token :End (see H-9).
H-5 (Where kind and normativity are declared). Pattern kind (for example, Architectural or Definitional) MUST be declared in the Header block, not encoded into the heading text. Normativity (normative or informative) MUST also be declared in the Header block when it deviates from the default.
If a reminder is needed for readers, authors MAY add a short parenthetical note at the end of the heading, for example (informative) or (non‑normative), but headings MUST NOT use square‑bracket tags.
H-6 (Heading levels). Heading levels MUST preserve a fixed offset between structural layers (Part or Cluster (flat) → Pattern → Pattern sections):
- Part and Cluster headings MUST use
#(level 1) across the file. - A Pattern heading MUST use
##(level 2). - Inside a pattern, each nested section MUST add exactly one
#per level (e.g.,## A.2 - …,### A.2:2 - …,#### A.2:2.1 - …).
H-7 (Ellipsis discipline). Authors MUST NOT use three consecutive dots (...) as punctuation in headings or narrative prose. Authors MUST use the Unicode ellipsis … (U+2026) instead. For editorial elisions in quotations, authors SHOULD prefer […] to make the omission explicit and distinguish it from retrieval truncation.
Exception: literal three‑dot sequences that are part of an external language’s syntax MAY appear only inside code spans or fenced code blocks.
H-8 (Normative keywords). The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119, as clarified by RFC 8174 (only when capitalised). Authors SHOULD avoid informal deontic phrasing (“need to”, “is required to”) in normative clauses.
Deontics vs admissibility. Use RFC keywords only for deontic obligations (requirements on authors, reviewers, implementers/tooling, or published pattern or companion texts). These concern things an agent can choose to do or omit. Do not use RFC keywords to state definitions, structural invariants, typing rules, or other admissibility conditions of the modeled world.
When you need an enforceable constraint that is mathematical rather than deontic, express it as a non‑deontic predicate using one of: Definition:, Invariant:, or Well‑formedness constraint: (optionally with formal quantifiers). Prefer mathematical terms like cardinality 1..1 (total), 0..1 (partial), or 0..n over deontic adjectives like “mandatory or optional” when the intent is cardinality, not duty.
Admissibility predicate discipline (recommended shape).
When expressing admissibility or validity constraints as predicates (Definition:, Invariant:, or Well‑formedness constraint:):
- Authors MUST NOT use RFC keywords inside the predicate block.
- Authors SHOULD give each predicate a stable identifier and short name (e.g.,
RA‑1 (Locality),RE‑3 (Method gate)), so that Conformance Checklist items can reference it without re‑authoring the rule. - Authors SHOULD write the constraint as a declarative predicate with a truth condition (optionally quantified), for example “every selected interval lies within the declared qualification window”, rather than as “X MUST …”.
- If the constraint needs to be checked as part of pattern conformance, authors SHOULD reference the predicate identifier from the Conformance Checklist, and state validator behaviour when relevant, rather than duplicating the predicate with RFC keywords.
H-9 (Footer marker sentinel). Footer marker SHALL be a single heading line whose FullId is the pattern ID followed by the reserved sentinel token :End (no ordinals, no title, no square‑bracket tags):
### <PatternId>:End
Apart from a retained published address under H-3, it is the only allowed heading inside a pattern whose section token is non‑numeric. It MUST be the final line of the pattern and MUST NOT carry any prose. Tooling and readers MUST treat it as a boundary sentinel, not as a semantic section.
H-10 (Publication-token classification and addressability). Before emitting an FPF-governed token as a reference, authors MUST classify it under exactly one of these seven E.8-local publication-token classes and use the matching form:
PatternRefuses one PatternID to name a pattern that continues across editions of the framework identified by the surrounding text. In the assembled publication being checked, it resolves to one complete H2 body, one matching:End, and a truthful ToC status for that PatternID. A reference intended to select the body published in one edition also names that framework edition. A structural checker may verify and report publication conformance but does not establish the pattern’s identity, status, or authority.PlannedCatalogEntrynames an explicit future catalogue commitment. It has no current pattern semantics, governing force, prerequisite force, or addressable body. A useful prose mention MUST sayplannedorfuture, and a current semantic dependency MUST cite existing content that supplies the needed definition, constraint, test, method, or other rule, or state the current gap.SectionRefnames one exact heading path inside one current pattern, one framework publication unit declared underE.11.PFP, or one non-framework Reference declared underE.11.DSG. Authors and tooling MUST read the complete section identifier and its declared scope before examining any substring. For example,STR.Reference:1returns to the Strategy Architectural Reference. It does not declare a pattern namedSTR.Reference. Similarly,Engineering.Reference:2.1returns to a section of the Engineering Suite Reference without declaring a pattern or a framework namedEngineering.Reference.LocalDeclaredIdnames an exact declaration within one pattern, such as a conformance clause, component, interface row, or predicate. Its scope is local unless an explicit stable anchor or a separate promotion decision establishes wider use.LocalAliasnames a declared compatibility alias and resolves to its declared canonical local target.PatternFamilySelectorselects a navigable pattern family using canonical spelling<base>.*. It requires a current base pattern and at least one current matching member and MUST NOT stand in for one exact governing target.NonReferenceTokenclassifies a schematic example or ordinary local prose/code that neither occupies a reference-bearing position nor declares a local public ID. This class denotes no reference. Key-like typography or backticks alone do not change that class.
A portable reference MUST let the reader recover the intended document within its publication set and the intended contribution from the reference and the context that travels with it. Preserve the complete PatternID or SectionRef when the contribution has one. Add the publication set, the document’s full title or its explicitly declared DocID only where that identification is not already unambiguous. Do not repeat a qualifier that the complete address and retained context already supply.
For example, once FPF Core is identified, C.39:4.1 is sufficient. Use FPF C.39:4.1 when the document qualifier is needed. Resolve the complete address under its declarations rather than inferring its scope from a fixed substring.
A DocID identifies a whole document. It is not a new PatternID, an edition identifier, a publication-unit identifier, a globally unique name, or an eighth publication-token class. An existing framework code may serve as its DocID only through an explicit declaration.
A whole-document reference needs only enough information to identify that document. A reference to an ordinary unnumbered heading adds its title without inventing a PatternID. Name a selected edition separately when its exact published body matters. When extracting a fragment, restore any identifying context that will no longer accompany it.
A URL, file path or service locator is an optional projection to an access carrier, not the portable reference’s identity. To resolve a reference, recover the document and publication set from the complete reference and retained context, then match the complete local address or named unit in the available text.
A catalogue may associate those declarations with current carriers. A changed carrier does not change the reference. Preserve any more precise valid SectionRef already stated in a link’s visible label even when the URL lands at its enclosing body.
If the document, target or requested edition cannot be recovered unambiguously, report that unresolved reference rather than silently substituting another document, section or edition. These requirements add no URI syntax, HTML anchor or service API.
Resolution and checking are declaration-first and context-sensitive. Authors and tooling MUST NOT split complete SectionRefs, strip a local-ID prefix, promote a local symbol by visual resemblance, or replace these classes with an ignore list. An unresolved token in a reference-bearing authoring form is an error. Ordinary code or local wording is not silently upgraded to a reference.
H-11 (Assembled Part boundaries and title agreement). In the assembled publication, every compact ToC Part label MUST be a bold separator with a blank line on both sides, not a duplicate structural Part heading. Its title and ASCII space-hyphen-space separator MUST agree exactly with the corresponding # Part <letter> - <title> body heading. A reserved body Part that has no compact ToC table, including current Part H, does not require an empty compact label or table.
Problem frame names the working situation. Generic Context and universal U.BoundedContext do not identify the actual value a claim needs.
For each use, go directly to the rule that supplies the needed value. Recover source-local meaning through F.0.1, use F.1 to select answer-changing sources, state ClaimScope through A.2.6, and use A.1.1 for an admitted bounded-model use.
Add F.17 only when a durable address or basis relation is needed, F.9 only for an obtaining Bridge between two exact local senses, and the applicable plane relation for a ReferencePlane claim. Otherwise leave the relation unasserted rather than inferring it from a shared word, source, or context.