fpf-authoring-conventions-style-guide

name: fpf-authoring-conventions-style-guide description: FPF Pattern E.8: FPF Authoring Conventions & Style Guide license: Apache-2.0 metadata: fpf_id: E.8 fpf_title: "FPF Authoring Conventions & Style Guide" allowed-tools: []

E.8 - FPF Authoring Conventions & Style Guide

Type: Architectural (A)
Status: Stable
Normativity: Normative (unless explicitly marked informative)

E.8:1 - Problem frame

FPF grows through the addition of patterns written by authors from many disciplines. Without a shared structure and voice, the framework would fracture, violating Pillars P‑1 Cognitive Elegance and P‑2 Didactic Primacy.

E.8:2 - Problem

Structural drift and stylistic fragmentation threaten three qualities:

1. Comparability – readers cannot align patterns lacking common headings.
2. Narrative cohesion – prose swings from dry jargon to informal blog style.
3. Auditability – missing sections hide safety checks (Archetypal Grounding, Bias‑Annotation).

E.8:3 - Forces

E.8:4 - Solution — One template, enriched by style principles

E.8:4.1 - Canonical Pattern Template

Within each pattern, the canonical section headings SHALL appear in the order below. For each canonical content section heading (1–12), the <Title> component (after the heading separator, e.g. -) MUST start with the canonical section title (case-insensitive match; canonical capitalisation preferred); an optional clarifier after an em dash is allowed (e.g., Solution — …). The Footer marker (section 13, if present) is a sentinel and is governed by H‑9 rather than the standard <FullId> - <Title> shape.

Extensibility. Authors MAY add additional sections. Prefer expressing them as subsections under the nearest canonical section (e.g., 4.1, 4.1.1 under Solution). If an additional top-level section is necessary, it MUST NOT delete or reorder the canonical sections and its title MUST NOT shadow a canonical title.

Mandatory vs optional.

• Canonical sections 1–13 are mandatory in every pattern.
• The escape hatch Not applicable is permitted only where explicitly stated below; when used, it MUST include a short justification (1 paragraph).

Template:

• Title line: Hashes + FullId + - + Pattern Title; optional (informative) note.
• Header block: Type, Status; optional Normativity override.

1. Problem frame
2. Problem
3. Forces
4. Solution
5. Archetypal Grounding (Tell–Show–Show; System / Episteme; Not applicable allowed only with justification)
6. Bias‑Annotation
7. Conformance Checklist
8. Common Anti‑Patterns and How to Avoid Them (Not applicable allowed only with justification)
9. Consequences
10. Rationale
11. SoTA‑Echoing (post‑2015 practice alignment; terminology drift & deltas; Not applicable allowed only with justification)
12. Relations
13. Footer marker

Footer marker. End each pattern with a single visible sentinel heading line on its own: ### <PatternId>:End. This makes truncation detectable even when HTML comments are stripped or surfaced by editors. The footer marker is intentionally content‑free: do not place prose under it.

Note. Pattern boundaries are still parseable by scanning for the next pattern heading (## …), but an explicit :End marker helps retrieval pipelines (and LLM prompts) distinguish “this chunk is the whole pattern” from “this chunk was cut mid‑pattern”.

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, so headings must be self‑identifying.

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 between <FullId> and <Title> is - (ASCII, space-hyphen-space). Legacy text may use -; tooling SHOULD treat the two as equivalent, and authors SHOULD migrate to - when touching a heading.

H‑3 (FullId). FullId is the full hierarchical address. For a pattern heading it is the pattern ID (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 pattern IDs.

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 legacy 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. Note: the Footer marker itself is exempt from ordinal encoding; it uses the reserved token :End (see H‑9).

H‑5 (Where kind and normativity live). Pattern kind (e.g., Architectural / Definitional) MUST be declared in the Header block, not encoded into the heading text. Normativity (normative / informative) MUST also live 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 (e.g., (informative) / (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 full stops/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 artefacts) — i.e., 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) / 0..n over deontic adjectives like “mandatory/optional” when the intent is cardinality, not duty.

Admissibility predicate discipline (recommended shape). When expressing admissibility/validity constraints as predicates (Definition: / Invariant: / 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 (optionally quantified), e.g., role ∈ Roles(context), rather than as “X MUST …”.
• If the constraint needs to be enforceable as part of a pattern’s contract, authors SHOULD reference the predicate identifier from the Conformance Checklist (and/or call out validator behaviour), 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 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.

Unification note: historic A‑ and D‑templates differed only by the presence/absence of Bias‑Annotation and Relations; the unified template keeps the headings everywhere while allowing explicit Not applicable statements when justified. The Alexandrian pattern canon historically calls Problem frame “Context”. FPF avoids that label because Context is already overloaded in FPF (e.g., U.BoundedContext and its Plain‑register label).

E.8:4.2 - Stylistic Principles (S‑0 … S‑13)

Authors use the principles as a scaffold, not a straitjacket: the goal is coherent, engaging insight.

S‑0 (Narrative Flow Seven‑Step Heuristic) — explanation Narrative flow is recommended to follow these steps: Hook → Frame → Weave → Anchor → Bridge → Flow → Close.

Brief explanations:

Narrative Flow Heuristic also operationalises S‑1 (Density w/o Jargon), S‑2 (Internal Cohesion), S‑4 (Contextualisation), and S‑6 (Quotable Closers).

E.8:4.3 - Autonomy authoring stub (mandatory when autonomy is claimed)

If a pattern or example claims autonomy for any Role/Method/Service:

1. Add a subsection “Autonomy (RoC‑E.16)” that lists:
   • AutonomyBudgetDeclRef (id, version, Scope (G), Γ_time),
   • Aut-Guard policy-id (PolicyIdRef),
   • OverrideProtocolRef (SpeechAct names, SoD),
   • pointer to where Green‑Gate applies in the Method steps,
   • where AutonomyLedgerEntry is recorded on U.Work.
2. Include one Tell‑Show‑Show vignette that demonstrates depletion and override handling.
3. Use LEX‑BUNDLE terms (Scope (G), Γ_time, Role/Method/Work). Avoid “validity”, “process”, “actor”, “system”, “mechanism” unless mapped to kernel types.

E.8:5 - Archetypal Grounding (System / Episteme)

Note: Prefer examples that reuse FPF’s own characteristics vocabulary (e.g., F (Formality) rather than “F‑score”) unless you explicitly mean an external metric and name it as such.

E.8:6 - Bias‑Annotation

Lenses tested: Gov, Arch, Onto/Epist, Prag, Did. Scope: Universal for the authoring conventions in this pattern. This guidance biases toward Did (readability, narrative flow) and Arch (template regularity) by design; the mitigation is explicit optionality (Not applicable) and the requirement to justify omissions in‑text.

E.8:7 - Conformance Checklist

CC style (canonical). Conformance Checklist items are obligations/conditions in the authoring plane: they constrain artefacts that claim conformance (and the reviewers/validators that accept them). A CC clause of the form “X SHALL …” is to be read as “In a conforming artefact, X SHALL …”, not as a deontic statement about the modeled world.

Preferred wording for new or edited CC items: start with an explicit conformance subject (e.g., “Authors …”, “Reviewers …”, “A conforming implementation …”, “A validator …”). If a CC item is enforcing an admissibility predicate, it SHOULD cite the predicate’s identifier (from a Definition: / Invariant: / Well‑formedness constraint: block) rather than restating the predicate as “X MUST …”. For boundary/interface/protocol/contract patterns, prefer A.6.B‑routed claim IDs (L/A/D/E) or cite an existing Claim Register (A.6.B:7) instead of restating mixed prose.

E.8:8 - Common Anti‑Patterns and How to Avoid Them

These failure modes recur in drafts and in downstream application. They are predictable ways the Forces in this pattern get violated.

E.8:9 - Consequences

E.8:10 - Rationale

Structure and style function as FPF’s grammar. By unifying what were once separate “template” and “style guide” patterns, authors face a single reference point that satisfies:

• P‑1 Cognitive Elegance – uniform, minimal surprises.
• P‑2 Didactic Primacy – narrative flow, dual archetype examples.
• Guard‑Rails 1 & 2 – no tool jargon, no notation lock‑in inside prose.

A unified template also improves retrieval: a chunk containing A.2:<n> - Bias‑Annotation remains self‑identifying even when parent headings are missing, and the recommended footer marker makes truncation detectable.

International and industry standards often speak in terms of conformance criteria. FPF uses the label Conformance Checklist to make adoption easier for engineers and managers.

E.8:11 - SoTA‑Echoing (normative; lineage & deltas to contemporary State‑of‑the‑Art)

Purpose. Make each pattern’s relationship to contemporary practice explicit and comparable without importing tooling or data governance. This section is prose‑first and notation‑independent.

Minimum contents (obligations).

1. Evidence binding (no duplicate SoTA). If a SoTA Synthesis Pack exists (G.2), this section SHALL cite its ClaimSheet IDs / CorpusLedger entries / BridgeMatrix rows as the source‑of‑truth for claims and report adopt/adapt/reject consistent with those IDs. Avoid forking an untracked SoTA narrative.
2. Sources (post‑2015). For Architectural patterns, cite ≥ 3 primary SoTA sources (standards/papers/books), with at least two independent Traditions. For Definitional patterns, cite ≥ 1 post‑2015 primary source and, where relevant, a short note on terminology drift/deprecations.
3. Practice alignment. For each cited item, state what is adopted/adapted/rejected and why (2–4 sentences).
4. Scale legality. If numeric operations are implied, bind to ComparatorSet/CG‑Spec and declare partial‑order stance (no hidden scalarisation).
5. Cross‑Context reuse. Any reuse across U.BoundedContext must surface Bridge+CL/Φ_plane policy‑ids (penalties affect only R_eff).
6. Lexical hygiene. Avoid “mapping” unless you mean an explicit Bridge/translation relation with loss notes.

Writing guidance (readability). Write short paragraphs, not tag lists. For each Tradition, provide (a) a one‑sentence capsule of the practice, (b) a one‑sentence comparison to the pattern’s Solution, (c) a one‑sentence adoption status with reason. Where helpful, add one System and one Episteme micro‑example (Tell–Show–Show).

Format: human‑first. A small table is allowed, but each row MUST be accompanied by 1–2 sentences as above. Vendor/tool tokens, file formats, or data schemas are out of scope.

E.8:11.1 - SoTA alignment for this pattern (E.8 self‑echo)

E.8:12 - Relations

• Builds on: E.6, E.7
• Constrained by: Guard‑Rails E.5.1–E.5.4 (lexical firewall, notation independence, etc.)
• Constrains: All patterns; the DRR template references the same section order.

E.8:End