Architecture Decision Records

ADR-0001: Three Pillars on a Computational-Mathematical Bedrock

STATUS: DRAFT

Context

The reference architecture needs a simple public-facing narrative while preserving technical rigor. The public story must be tellable in a sentence, survive on a landing page, and still be honest about the computational and mathematical machinery underneath — without that machinery either disappearing from view or crowding the story it enables.

Decision

The ecosystem is described using three pillars: AI-Driven, Physics-Based, and Trusted. Computational and mathematical foundations are not a fourth pillar; they are the bedrock beneath all three pillars: they ground claims, connect representations, compute predictions, and make evidence testable.

Consequences

The narrative remains accessible while technical communications can surface the deeper computational foundations needed for implementation, verification, and long-term credibility. Every pillar visibly stands on the same foundations. The bedrock is easy to under-communicate, and every future artifact must maintain the pillar/bedrock distinction deliberately — now policed by the Appendix C narrative guardrails.

ADR-0002: Markdown as Source of Truth with Automated Builds

STATUS: DRAFT

Context

jBOK is intended to become the authoritative source for a living architecture suite, not merely a storage location for generated PDF and DOCX files.

Binary documents are difficult to diff, review, merge, and audit. The project needs full change history, meaningful diffs, repeatable builds, and source-level collaboration.

Decision

Markdown is the source of truth for the main book, appendices, specifications, ADRs, governance material, and roadmap material.

The main book SHOULD be organized as one Markdown file per chapter under book/main/source/chapters/.

Each appendix SHOULD maintain its own Markdown source and independent version metadata.

PDF and DOCX outputs SHOULD be generated automatically from Markdown using repository build scripts.

Diagrams SHOULD be kept under version control using textual or reviewable source formats; any binary-only diagram exception MUST document why no textual or reviewable source format is practical.

GitHub Actions SHOULD build the book on every commit and pull request.

Consequences

The repository becomes the authoritative source for the living architecture.

Reviewers can inspect meaningful textual diffs instead of opaque binary document changes.

Generated artifacts can be reproduced from source.

Binary exports remain useful for distribution, but they are not the canonical source.

Build failures become visible early through continuous integration.

Maintaining reproducible exports requires build-tool upkeep, and source types not checked automatically require editorial discipline.

ADR-0003: Five-Volume Reference Architecture Suite — Vision, Specifications, Implementations, Research, Conformance

STATUS: DRAFT

Context

jBOK is larger than a single book. The stable narrative, living specifications, implementation examples, research agenda, and conformance mechanisms evolve at different rates.

A single monolithic document would make the architecture harder to maintain, version, review, and extend.

Decision

jBOK will be organized conceptually as a Reference Architecture Suite:

• Volume 1: The Vision and Architecture
• Volume 2: The Living Specifications
• Volume 3: Reference Implementations
• Volume 4: The Research Agenda
• Volume 5: Conformance and Accreditation

The repository MAY keep appendices at the top level to preserve independent versioning, even when those appendices are conceptually part of Volume 2.

Consequences

The main book can remain relatively stable while appendices, specifications, implementation examples, research challenges, and conformance assets evolve independently.

This structure supports RFC-style versioning, meaningful diffs, repeatable builds, and long-term governance.

The reference architecture remains independent of any specific implementation.

ADR-0004: Implementation Profiles as Evidence Into the Architecture

STATUS: DRAFT

Context

The Reference Architecture Suite, including the living specifications and Appendices C and F, establishes that named implementations must be referenced only as implementation profiles: one possible realization of the reference architecture, never a definition of it. The first working implementation now exists and has produced architecture-relevant evidence (validated decision-fork defaults, conformance lessons, and null results worth recording). The repository needs a durable, organization-neutral home for that material that cannot drift into implementation-centric framing.

Decision

Implementation profiles are maintained as living specifications under specs/implementation-profiles/, one document per named implementation. Each profile follows the common specification metadata (identifier, version, status, scope, dependencies, compatibility policy, conformance evidence, change history) and additionally documents deployment pattern, security assumptions, data handling, compute environment, interface versions, maturity level against the capability maturity framework, and explicit deviations from the reference architecture.

Profiles provide evidence to the reference architecture; they do not impose requirements on it. A profile MAY motivate a revision to the book or an appendix; the book MUST NOT depend on a profile.

Consequences

The architecture gains a conformance feedback loop: implementations report what the contracts felt like to build against, which decision-fork defaults survived contact with reality, and where the reference layers lack substance. Multiple independent profiles can coexist without any becoming canonical. Profile authors accept the obligation to record deviations and gaps honestly, including null results.

ADR-0005: Six Interface Contract Families, with Security as a Distinct Family

STATUS: DRAFT

Context

Independent contributors need the same names for the boundaries where agents, models, evidence, trust, semantics, and security interoperate. The reference architecture requires a consistent initial taxonomy for interface contracts across the main book and the living specifications. Security obligations intersect with other contracts, but they also define distinct access-control, authorization, confidentiality, integrity, and boundary requirements that must remain explicit and independently governable.

Decision

The initial interface-contract families are:

• Agent contracts
• Model contracts
• Trust contracts
• Evidence graph contracts
• Ontology and semantic contracts
• Security contracts

Their specification identifiers are agent-contracts, model-contracts, trust-contracts, evidence-graph, ontology, and the reserved security-contracts.

Security contracts are a distinct family because security boundaries and controls apply across ecosystem capabilities and require explicit compatibility and conformance treatment beyond the concerns of any single capability contract.

New interface-contract families are additive and require an ADR.

Consequences

The main book and Appendix G share a canonical six-family taxonomy. Security requirements remain visible as cross-cutting interface obligations rather than being implicit within other contract families. The taxonomy can evolve without disrupting existing families, while ADR review preserves architectural traceability for each addition.

ADR-0006: Model Contracts Declare Parameter Origins and Completeness

STATUS: DRAFT

Context

A model should not gain trust merely because nobody declared where its decision-relevant numbers came from.

Model contracts declare assumptions, calibration basis, dependencies, uncertainty behavior, and operational limits, but they do not yet define how decision-relevant parameter origins or the completeness of those declarations are represented. Requirements for honest parameter classification and explicit missingness are generalized from evidence documented in the JWM implementation profile, without making that implementation a dependency of the reference architecture.

Decision

Model contracts SHOULD classify each decision-relevant parameter using a declared origin vocabulary that distinguishes, at minimum, derivation from first principles, published literature, measurement, calibration by a recorded procedure, pass-through configuration, hand tuning without an external anchor, and undischarged assumption. Hand tuning and assumptions remain legitimate when disclosed, while presenting a tuned constant as first-principles physics violates the contract.

Model contracts should report classified and total parameter counts without hiding unclassified parameters. They SHOULD represent completeness explicitly as declared, partially declared, or undeclared; absence of a declaration MUST NOT be interpreted as confidence. Whether missingness blocks execution remains a separately stated policy decision.

Consequences

Model contracts provide an implementation-neutral account of parameter origins and make incomplete provenance visible. Consumers can distinguish disclosed tuning or assumptions from evidence-backed origins without conflating completeness with confidence. Execution policy remains independently governable, allowing the same contract semantics to support different assurance contexts.

ADR-0007: Design Philosophy Evolution — Durable Values, Evolving Mechanisms, Five New Principles

STATUS: DRAFT

Context

The design philosophy stated mechanisms where it meant terminal values, and was silent on properties that implementation evidence has shown to be load-bearing. "Human-Directed Outcomes" named a mechanism — a person directing each outcome — without stating the value it serves or how the mechanism may evolve. "Replaceable by Design" named a testable structural property but understated the goal it exists to serve. The philosophy also did not acknowledge that trusted decision ecosystems are dynamical systems in live contact with the physical world, did not state how deterministic and stochastic treatment relate to inspired confidence, and said nothing about emergent structure arising within the ecosystem or how continuous learning and self-improvement are governed.

Decision

The design philosophy is revised as follows. Terminal values are durable; mechanisms evolve under governance.

Durable is not frozen. Mechanisms may adapt continuously under evidence and accreditation. Terminal values change rarely, only by human insight, and only through an ADR that names what was learned and why the value changed. The ecosystem may occasion such insight, but only humans revise the values.

Human Authority over Outcomes replaces Human-Directed Outcomes. The terminal value is outcomes that match human intent, judged with human-aligned discernment, judgment, and taste. The mechanism follows a delegation arc: direction of individual outcomes today; as evidence accumulates, delegation of discernment and judgment within human-accredited intent envelopes. Delegation is expressed through agent-contract authority modes (escalate, recommend, decide), is earned per capability and per context of use through the capability maturity framework, and is always bounded, monitored, and revocable through accreditation conditions and runtime assurance. Authority boundaries remain explicit at every maturity level, and an identified authority always accepts residual risk. Unqualified acceptability is not the standard: a claim that automated judgment is human-aligned is an alignment claim, and it requires a validation referent, uncertainty characterization, and accreditation like any other claim.

Adaptable by Design replaces Replaceable by Design. Replaceability behind stable interfaces remains the testable floor and is unchanged as a conformance expectation. Adaptability is the goal the floor serves: capabilities SHOULD be able to reconfigure, recalibrate, and learn within their validity envelopes without disrupting the ecosystem. Adaptation is governed change — it produces evidence, respects contracts, and triggers re-review when an envelope is crossed.

Contact with Reality is added. Trusted decision ecosystems are dynamical systems coupled to the physical world. Contracts and evidence SHOULD account for real-time observation, state estimation, and prediction, and models SHOULD be judged by their forecasts against real-world referents, not only by retrospective validation.

Calibrated Confidence is added. Deterministic structure and stochastic treatment are balanced deliberately, and uncertainty is quantified and reported so that confidence is inspired by measurement rather than assumed. Confidence language in any ecosystem artifact SHOULD trace to uncertainty-quantification evidence. This is the working face of the Trusted pillar.

Emergence Recognized and Leveraged is added. The ecosystem SHOULD include watcher and recognizer capabilities that detect emergent structure, behavior, and design elements arising within the framework. Recognized emergence is assessed as evidence; capture MAY occur only after human assessment records reproducibility, usefulness, uncertainty, alternative explanations, compatibility impact, and consequence. Continuous learning and recursive self-improvement are goals pursued within this governance: an improvement to the ecosystem — including an improvement to the improver — is proposed, evidenced, accredited, and bounded like any other change. Evolution without Disruption applies to self-improvement itself.

Open by Design, Evidence over Assertion, Trust through Transparency, Physics Informs AI, Evolution without Disruption, and Stable Interfaces, Evolving Implementations are unchanged.

Consequences

The philosophy names its terminal values and lets mechanisms mature without renegotiating principles — while reserving a deliberate, human-authored path for the values themselves to grow as human understanding grows. The delegation arc gives the authority-boundary vocabulary and the maturity framework a shared trajectory, and rules out acceptability without an identified acceptor. Adaptability subsumes replaceability without weakening it as a testable property. Reality contact and calibrated confidence make the dynamical, predictive, and uncertainty-bearing character of the ecosystem part of the public narrative rather than an implementation detail. Emergence recognition creates an explicit architectural home for continuous learning, and binds recursive self-improvement to the same evidence and accreditation discipline as every other change.

ADR-0008: Recognizer as a Specialized Agent Role

STATUS: DRAFT

Context

ADR-0007 adds Emergence Recognized and Leveraged to the design philosophy, calling for watcher and recognizer capabilities that detect emergent structure, behavior, and design elements while requiring recognized emergence and recursive self-improvement to remain governed by evidence, accreditation, and bounded authority. The architecture needs an explicit home for recognition without prematurely expanding the interface-contract taxonomy.

Recognition is a bounded role and an evidence-producing workflow. A recognizer observes a declared scope and window, tests specified emergence conditions against a baseline, and issues a report for human assessment. Identity, authority, evidence obligations, oversight, failure, escalation, and monitoring are already concerns of agent contracts. ADR-0005 reserves additions to the interface-contract families for ADR review, and no demonstrated cross-family interoperability need yet requires recognition to be independently governed as a new family.

Decision

The watcher/recognizer capability is realized as a specialized agent role: an agent contract with a recognition profile, accompanied by a Watcher/Recognizer Agent role in the Appendix E agent catalog. It is not a new interface-contract family.

Recognition reports are evidence. Every recognition report passes through a human-assessment gate before any candidate is captured into a contract, profile, or the architecture. A recognizer's own report is never the sole evidence for increasing that recognizer's authority or promoting it. Recognizer-driven change may open a proposal, but it never bypasses compatibility review, versioning, conformance, accreditation, or deployment gates.

The placement SHOULD be reviewed when recorded implementation evidence identifies multiple non-agent producers, two or more independent implementations, or incompatible recognition-report schemas or required fields. Those conditions may justify a distinct Recognition Contracts family, but adding that family requires a later ADR under ADR-0005.

Consequences

Recognition gains a clear architectural home without duplicating agent-charter concerns or adding an unproven contract family. Implementations can realize the role as software, a supervised workflow, a service, or a hybrid while preserving explicit authority, evidence, monitoring, and human oversight.

Recognition remains advisory and evidence-producing: capture is a separately authorized governance action, and self-observation cannot bootstrap authority. Existing change, conformance, accreditation, and deployment controls continue to govern every recognizer-driven proposal. The taxonomy can still evolve if interoperability evidence later demonstrates that recognition reports need an independently governed contract family.

ADR-0009: ADR Lifecycle (Draft → Proposed → Accepted), Template, and CI-Checked Registry

STATUS: DRAFT

Context

The decision record has outgrown its conventions. Appendix C requires its inventory to be updated in the same change that adds an ADR, yet ADR-0008 was absent from the inventory until 2026-08-01. Appendix C lists twelve fields an ADR SHOULD include, yet ADR-0001 through ADR-0008 used a lean four-section form that omits alternatives, risks, dates, deciders, and version impact. No document stated who accepts an ADR, what evidence closes review, or how statuses move. All eight existing ADRs were returned to Draft on 2026-08-01 for individual reproofing. That effort needs the very rules this ADR records: an explicit lifecycle, a template that captures decision evidence, a way to express that a later ADR extends an earlier one without invalidating it, and a registry that cannot silently drift.

Decision

An ADR moves Draft → Proposed → Accepted; Rejected is terminal from Draft or Proposed; an Accepted ADR may later become Deprecated or Superseded by a named ADR. Extension is a relationship, not a status: a later ADR declares that it extends an earlier one, the earlier record gains the back-reference in the same change, and an extended decision remains in force. Each ADR names its Deciders, and transitions follow the governance review gates. New ADRs use a merged template — MADR structure plus jBOK-specific fields (version impact, open research questions, risks, the leave-open outcome, and validation and compliance). Numbering is sequential and monotonic: numbers are never reused or reassigned, and the index lives in exactly two places — filename and H1 title — which the validator requires to agree. The Appendix C inventory is machine-checked in CI: registry drift is a conformance failure.

Consequences

Registry drift becomes a CI failure instead of a discovery during review. The reproofing pass has explicit start and end states per ADR, and extension chains stay auditable in both directions without falsely retiring extended decisions. The cost is more ceremony per record and a migration obligation for the eight existing ADRs as each is reproofed.

ADR-0010: Agent Charters: Hashed, Pinned Authority Records in the Agent Contracts Family

STATUS: DRAFT

Context

Agent recommendations can carry evidence while the agent itself remains unauditable: nothing standing records what an agent is allowed to do, what it reads, what it emits, and where its competence ends. The Appendix A attack plan marks agent charters as buildable groundwork, and ADR-0005 already provides the Agent Contracts family to hold the artifact. A subtler question arrives with charters: when a human directive, a charter bound, and a physical envelope disagree, which wins?

Decision

An agent charter is a normative, content-addressed artifact of the Agent Contracts family declaring identity, permitted command sources, readable components, constraint set, evidence duties, and escalation triggers. Any agent output presented to a decision gate, referenced by a trust claim, or consumed as decision evidence MUST pin the charter hash in its execution record and linked evidence-graph artifact. Where multiple constraint sources apply, the resolution order must be declared and auditable — but no universal precedence rule or inter-agent consensus protocol is claimed; those remain open research.

Consequences

Agents become auditable as standing entities, and any future charter language or consensus method inherits the pinning and verification machinery unchanged. Charter hashes give accreditation and revocation a concrete anchor, at the cost of schema governance and runtime pinning on decision paths.

ADR-0011: Cryptographic Hashes and Embedded Validity Envelopes at Trust Boundaries — Signatures Optional but Verified

STATUS: DRAFT

Context

Within one trust domain, content-addressing and verification on ingest are established integrity mechanisms. Crossing an organizational boundary adds two requirements the contracts acknowledge but do not decide: authenticity — who made this artifact — and scope — what context it was validated for. The pragmatic error to avoid is inventing a bespoke trust framework instead of making artifacts signable and envelopes machine-checkable. Extends ADR-0006.

Decision

The governed families are trust contracts and evidence graph; extending the rule to further families requires a minor-version change in each. Any evidence-bearing artifact that crosses a trust boundary MUST carry a cryptographic content hash and embed its validity envelope, so reuse-outside-context is detectable by the receiving party alone. Every evidence-bearing artifact reserves an optional signatures block — key identifier, algorithm, signature over the canonical content hash, signer role — verified when present, with absent, present-valid, present-invalid, and unverifiable states reported distinctly. Hashes and signatures establish integrity and authenticity claims only; fitness for a decision context remains the business of trust contracts and accreditation.

Consequences

Evidence can cross organizational boundaries without trusting the channel, envelope violations degrade trust visibly instead of silently, and the signature block gives future attestation standards a stable mount point. Export tooling must canonicalize content for hashing, and the conformance suite must pin the canonical form early.

ADR-0012: Evidence Claims at Decision Gates: Interval, Sample Size, Uncertainty Source, Traceability

STATUS: DRAFT

Context

ADR-0007 makes Calibrated Confidence a terminal value: confidence language should trace to uncertainty-quantification evidence. But no contract defines the minimum form that evidence takes, so the principle is currently unenforceable — while decision-grade uncertainty propagation through hybrid model chains remains among the hardest open research challenges. Extends ADR-0007.

Decision

An evidence claim offered at a decision gate must report an interval and sample size for any ensemble-scored rate — never a bare fraction — the threshold or context when one applies, a dominant uncertainty source named from a controlled vocabulary, and confidence language traceable to the uncertainty record it summarizes. Chained artifacts may reference upstream uncertainty records. This decision explicitly claims no propagation calculus: composing uncertainty across a chain remains the consumer's judgment, informed by the referenced records. Meeting the floor makes a claim reportable at a decision gate; it does not by itself make the uncertainty analysis adequate.

Consequences

Calibrated Confidence becomes a conformance property, and claims become comparable across models, domains, and profiles at the floor. The floor verifies presence and traceability, not statistical validity — floor-level uncertainty reporting must not be mistaken for sufficient uncertainty quantification.