FPF Reference

    Principle-Framework Architecture Decision

    E.4.PFAD · Stable · Architectural (A) · Normative unless marked informative. · Part E - The FPF Constitution and Authoring Guides

    About this pattern

    This is a generated FPF pattern page projected from the published FPF source. It is canonical FPF content for this ID; it is not a FPF Reference product feature page.

    How to use this pattern

    Read the ID, status, type, and normativity first. Use the content for exact wording, the relations for adjacent concepts, and citations to keep active work grounded without pasting the whole specification.

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

    Use this pattern when a framework author or steward must decide the architecture of one FPF-grounded domain principle framework or local practice framework: its purpose, selected pattern set, relation structure, publication or access carrier, dependency boundary, names, source basis, quality route, and currentness route.

    Relations

    E.4.PFADbuilds onFPF Ecosystem Family Architecture
    E.4.PFADbuilds onDesign-Rationale Record (DRR) Method
    E.4.PFADbuilds onProject Architecture Decision After Candidate Synthesis
    E.4.PFADcoordinates withArchitecture Decision Record Projection
    E.4.PFADcoordinates withMulti‑View Publication Kit
    E.4.PFADcoordinates withPattern-Framework Relation and Edition Discipline
    E.4.PFADcoordinates withLocal-First Unification Naming Protocol
    E.4.PFADcoordinates withSoTA Harvester & Synthesis
    E.4.PFADcoordinates withTelemetry-Driven Refresh & Decay Orchestrator
    E.4.PFADcoordinates withFPF Pattern-Quality Evaluation CharacteristicSpace
    E.4.PFADcoordinates withPattern Quality Gates: Review and Refresh Profiles
    E.4.PFADcoordinates withProject Architecture Decision After Candidate Synthesis
    E.4.PFADcoordinates withFPF Ecosystem Family Architecture
    E.4.PFADcoordinates withDomain Principle Framework Package-Adequacy Evaluation CharacteristicSpace
    E.4.PFADcoordinates withQuality Improvement Loop Method
    E.4.PFADcoordinates withStructural Information Adequacy for Architecture Capture and Source Return
    E.4.PFADcoordinates withStructural Correspondence, Equivalence, and Morphism Adequacy
    E.4.PFADcoordinates withStructural Synthesis and Discovery Adequacy
    E.4.PFADoutline parentFPF Ecosystem Family Architecture
    E.4.PFADoutline prev siblingFirst Principles Framework Form and Publication-or-Access Carrier Assembly
    E.4.PFADoutline next siblingDomain Principle Framework Authoring and Publication-or-Access Carrier Assembly
    E.4.PFADexplicit referenceDesign-Rationale Record (DRR) Method
    E.4.PFADexplicit referenceProject Architecture Decision After Candidate Synthesis
    E.4.PFADexplicit referenceArchitecture Decision Record Projection
    E.4.PFADexplicit referenceUnidirectional Dependency
    E.4.PFADexplicit referencePattern-Framework Relation and Edition Discipline
    E.4.PFADexplicit referenceMulti‑View Publication Kit
    E.4.PFADexplicit referenceDomain Principle Framework Package-Adequacy Evaluation CharacteristicSpace
    E.4.PFADexplicit referenceFPF Pattern-Quality Evaluation CharacteristicSpace
    E.4.PFADexplicit referenceQuality Improvement Loop Method
    E.4.PFADexplicit referenceFPF Ecosystem Family Architecture
    E.4.PFADexplicit referenceSoTA Harvester & Synthesis
    E.4.PFADexplicit referenceTelemetry-Driven Refresh & Decay Orchestrator
    E.4.PFADexplicit referencePattern Quality Gates: Review and Refresh Profiles
    E.4.PFADexplicit referenceLocal-First Unification Naming Protocol
    E.4.PFADexplicit referenceStructural Information Adequacy for Architecture Capture and Source Return
    E.4.PFADexplicit referenceStructural Correspondence, Equivalence, and Morphism Adequacy
    E.4.PFADexplicit referenceStructural Synthesis and Discovery Adequacy

    Content

    Problem frame

    Use this pattern when a framework author or steward must decide the architecture of one FPF-grounded domain principle framework or local practice framework: its purpose, selected pattern set, relation structure, publication or access carrier, dependency boundary, names, source basis, quality route, and currentness route.

    Primary EntityOfConcern: PrincipleFrameworkArchitectureDecision@Context, a framework-local architecture decision relation with explicit slots. The first useful output is a filled decision relation, not an ADR document and not the realized framework itself.

    Use this pattern only when the decision has framework-specific obligations beyond generic architecture-decision practice. If the decision only needs ordinary decision rationale or ordinary project architecture decision slots, use E.9, C.32.PAD, and C.32.ADR directly.

    Problem

    Framework architecture decisions recur in FPF-grounded work. A steward must decide whether a set of patterns belongs in Core, in a domain framework, in a local framework, or in publication and pedagogy. They must also decide how the framework depends on FPF Core, what edition boundary it has, what sources ground it, what names are admissible, and which carriers publish or expose the framework.

    If those decisions are hidden in prose, table shape, or an ADR-like file, later maintainers cannot tell which structure was selected, which alternative was rejected, what consequences were accepted, or when the decision should be repaired or superseded.

    Forces

    ForceTension
    Decision memoryThe framework needs durable rationale, but decision memory must not be confused with the framework structure itself.
    Framework-specific slotsGeneric decision patterns carry much of the method, but framework editions add dependency, naming, source-return, publication, and currentness obligations.
    Lightweight publicationADR-like records are useful, but their headings do not create the decision relation.
    EvolutionFramework decisions may become obsolete when sources, Core editions, domain scope, or local use changes.
    Non-duplicationA child pattern must not repeat E.9, C.32.PAD, or C.32.ADR without adding framework-specific value.

    Solution

    Create one PrincipleFrameworkArchitectureDecision@Context relation before publishing the decision through any ADR-like carrier.

    PrincipleFrameworkArchitectureDecision@Context:
  frameworkDecisionId
  governedFrameworkRef
  boundedContextRef
  frameworkEditionRef
  fpfCoreEditionRef
  decisionQuestion
  sourceBasisRefs
  sotaSynthesisPackRefs?
  namingDecisionRefs
  selectedPatternSetRefs
  selectedPatternRelationRefs
  publicationUnitRefs
  accessCarrierRefs?
  dependencyAndEditionRefs
  qualityEvaluationRefs
  admissionReviewRefs
  rejectedAlternatives
  rationaleRefs
  consequences
  publicationCarrierRefs?
  sourceReturnConditions
  refreshOrSupersessionConditions

    Fill the relation in this order:

    1. State the decision question as an architecture question about the framework edition.
    2. Name the bounded context, governed framework, and FPF Core edition dependency.
    3. List the source basis and SoTA synthesis packs that make the decision admissible.
    4. Select the pattern set and relation records, or state why the decision is not yet ready.
    5. Select the publication or access carrier only after the structure being exposed is clear.
    6. Record dependency and edition effects under [E.5.3](/generated/patterns/E.5.3) and [E.4.PFR](/generated/patterns/E.4.PFR).
    7. Record naming decisions or required [F.18](/generated/patterns/F.18) name-card work.
    8. Record rejected alternatives, rationale, consequences, quality route, source-return route, and refresh or supersession conditions.
    9. Publish the decision projection through [C.32.ADR](/generated/patterns/C.32.ADR) or [E.17](/generated/patterns/E.17) only after the decision relation exists.

    qualityEvaluationRefs and admissionReviewRefs are distinct reference families. qualityEvaluationRefs point to [E.4.DPF.DA](/generated/patterns/E.4.DPF.DA) package adequacy, [E.21](/generated/patterns/E.21) pattern-quality evaluation, or [E.23](/generated/patterns/E.23) improvement evidence. admissionReviewRefs point to [E.19](/generated/patterns/E.19) only when the decision is being used to claim admission, profile gating, external-review readiness, or landing readiness.

    Demotion condition: if no framework-specific slots are live, do not keep this pattern in play. Use [E.9](/generated/patterns/E.9) for rationale, [C.32.PAD](/generated/patterns/C.32.PAD) for project architecture decision structure, and [C.32.ADR](/generated/patterns/C.32.ADR) for the publication projection.

    Archetypal Grounding

    Tell: A team wants a hydroponic-cucumber domain principle framework. The PFAD decision asks whether the framework depends directly on FPF Core only, or also on an agriculture-domain framework edition; which crop-growth concerns become first patterns; which source packs are strong enough; and which publication or access carrier will expose the framework.

    Show: A Codex local practice framework has process patterns for baton handoff and prelanding checks. The decision records that these are local practice framework patterns, not FPF Core patterns. It names the FPF Core edition, selected local process patterns, local publication unit, source-return owners, and refresh conditions.

    Show: An ADR-like file saying "accepted: create domain framework" is insufficient. The decision relation must name selected pattern set, dependencies, source basis, rejected alternatives, consequences, and repair conditions before the ADR-like carrier can be trusted as a projection.

    Filled decision slice:

    PrincipleFrameworkArchitectureDecision@HydroponicCucumberDomain:
  frameworkDecisionId: PFAD-HC-001
  governedFrameworkRef: HydroponicCucumberPrincipleFramework@GreenhouseCropDomain
  boundedContextRef: commercial greenhouse cucumber production
  frameworkEditionRef: HC-DPF-0.1-draft
  fpfCoreEditionRef: FPFCorePatternSet@current
  decisionQuestion: Which first pattern set and relation structure should carry crop-growth architecturing guidance?
  sourceBasisRefs: G2-HC-source-pack, greenhouse-control source notes, accepted FPF ecosystem DRR
  namingDecisionRefs: F18-HC-framework-name-card-required
  selectedPatternSetRefs: problem-framing, nutrient-monitoring, climate-control interpretation, harvest-feedback patterns
  selectedPatternRelationRefs: PFR-HC-source-reuse, PFR-HC-specialization, PFR-HC-publication
  publicationUnitRefs: HC-all-in-one-carrier-readme-and-toc
  accessCarrierRefs: HC-grower-skill-pack-or-MCP-route-if-built
  dependencyAndEditionRefs: depends on FPFCorePatternSet@current; no Core reverse dependency
  qualityEvaluationRefs: E21-HC-first-pattern-evaluation
  admissionReviewRefs: none until admission is claimed
  rejectedAlternatives: land into FPF-Spec.md; publish only a crop checklist
  rationaleRefs: source-pack claim sheet and E.4 family map
  consequences: faster domain guidance; explicit refresh debt when sources or Core edition change
  publicationCarrierRefs: HC-all-in-one-carrier
  accessCarrierRefs: HC-grower-skill-pack-or-MCP-route-if-built
  sourceReturnConditions: return to G.2 when source pack loses a rival horticulture tradition
  refreshOrSupersessionConditions: G.11 refresh when Core edition or greenhouse practice changes

    Bias-Annotation

    The main drift is carrier-first decision making: a team starts from ADR headings, a status field, or a template and assumes that filling the file has made the decision. The repair is to fill the decision relation first and publish a projection second.

    The second drift is child-pattern duplication: PFAD can become a local restatement of generic decision practice. The repair is to keep only the framework-specific slots live and return generic decision work to E.9, C.32.PAD, and C.32.ADR.

    Conformance Checklist

    CheckPassing condition
    CC-PFAD.1 Decision relation existsA filled PrincipleFrameworkArchitectureDecision@Context relation exists before any ADR-like publication is treated as the decision.
    CC-PFAD.2 Framework-specific slots liveThe decision uses at least one framework-specific slot: edition dependency, selected pattern set, relation graph, publication carrier, access carrier, name cards, source-return, quality route, or currentness route.
    CC-PFAD.3 Generic owners reusedRationale uses E.9; project architecture decision shape uses C.32.PAD; publication projection uses C.32.ADR or E.17.
    CC-PFAD.4 Alternatives and consequences presentRejected alternatives, rationale, consequences, and repair or supersession conditions are recoverable.
    CC-PFAD.5 Source and name routes presentSource packs, source-return conditions, and required name-card work are named.
    CC-PFAD.6 Quality and admission separatedE.21 quality evaluation refs and E.19 admission review refs are separate or explicitly absent.
    CC-PFAD.7 Demotion checkedIf framework-specific obligations are absent, the decision is handled directly by neighboring patterns.

    Common Anti-Patterns and How to Avoid Them

    Anti-patternWhat failsRepair
    ADR as decisionA publication projection is treated as the decision relation.Fill PrincipleFrameworkArchitectureDecision@Context, then project it through C.32.ADR if useful.
    Template-led selectionHeadings decide what evidence is gathered.Start from the architecture question, source basis, alternatives, selected structures, and consequences.
    PFAD overgrowthThe pattern repeats generic decision practice.Demote to E.9 plus C.32.PAD and keep only a relation row if no framework-specific slot is active.
    Hidden Core changeA domain or local decision silently changes FPF Core meaning.Record framework family and dependency direction under E.4 and E.5.3.

    Consequences

    PFAD makes framework decisions more inspectable, because a later maintainer can recover the decision question, source basis, selected structures, rejected alternatives, and repair conditions. The cost is an extra decision relation before publication.

    The pattern also constrains ADR use. ADR-like records remain useful, but they become projections of a decision relation rather than the place where the ontology is invented.

    Rationale

    FPF already has decision, architecture decision, and ADR-projection patterns. The reason PFAD exists is narrower: framework authors repeatedly need the same framework-specific slots that generic decision patterns do not keep visible by default. Those slots are edition dependency, selected pattern set, relation structure, publication carrier, access carrier, source-return, naming, quality route, and currentness route.

    PFAD is therefore a specialization by obligation, not by vocabulary. If those obligations are not live, the specialization has no value.

    SoTA-Echoing

    ClaimExact source ref and statusPattern locus changedAdoption status
    Architecture decisions need context, decision, status, consequences, and supersession memory, but the record must not replace the decision relation.Nygard, Documenting Architecture Decisions, 2011 lineage source still current for compact ADR section functions, https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions; MADR, maintained template practice, current projection-format source, https://adr.github.io/madr/.Solution requires PrincipleFrameworkArchitectureDecision@Context before C.32.ADR projection; filled decision slice includes rejected alternatives, consequences, and supersession condition.Adopt section-function memory; adapt by making ADR-like text a projection of a prior FPF relation.
    Architecture decision records need concern, rationale, and description-boundary discipline.ISO/IEC/IEEE 42010:2022, official current standard ref for architecture-description concepts and architecture-versus-description boundary, https://www.iso.org/standard/74393.html.Problem frame says first output is relation, not ADR or realized framework; Relations keeps C.32.PAD and C.32.ADR as owners.Adopt rationale recovery; adapt to framework selected structures, source-return, and receiving owners.
    A framework-decision specialization must remain justified by recurring local obligations and near misses.Riehle, Harutyunyan, Barcomb, Pattern Discovery and Validation Using Scientific Research Methods, arXiv:2107.06065, 2021 current validation-practice source.Demotion condition, Conformance Checklist, and Common Anti-Patterns require PFAD to collapse when framework-specific slots are absent.Adopt validation pressure; reject a child pattern that only repeats generic decision slots.
    Compatibility, deprecation, and supersession need impact thinking beyond a label or status field.Semantic Versioning 2.0.0, current-standard compatibility-boundary practice, https://semver.org/spec/v2.0.0.html; Chen et al., Breaking Changes in Software Ecosystems: A Systematic Literature Review, arXiv:2605.24397, 2026 current SLR, https://arxiv.org/abs/2605.24397.refreshOrSupersessionConditions, dependencyAndEditionRefs, and E.4.PFR relation exits become required PFAD slots.Adapt compatibility-impact discipline to framework editions; reject software package, build, and binary semantics.

    Relations

    • Uses: E.9 as the rationale kernel for framework-local architecture decisions; it specializes only the recurring framework-specific obligations and does not create a second generic decision ontology.
    • Coordinates with: C.32.PAD for architecture-decision slot discipline.
    • Coordinates with: C.32.ADR and E.17 for decision publication projections.
    • Coordinates with: E.4 for family membership and selected structures.
    • Coordinates with: E.4.PFR for dependency, edition, compatibility, relation, and supersession effects.
    • Coordinates with: F.18, G.2, G.11, E.4.DPF.DA, E.21, E.23, C.33, C.34, and C.35 for name, source, currentness, package adequacy, pattern quality, preservation, and produced-carrier claims.

    E.4.PFAD:End

    Last Updated: 2026-06-26 — this section last modified in upstream FPF commit f1d0f931 (github.com/ailev/FPF)