SOFIA — ADR Index

ADR-001 — Semantic versioning (semver)

Status: Accepted Date: 2026-03-30 Author: Mira (architecte)

Context

SOFIA is an open source product published on GitHub (oxynoe-dev/sofia). Versioning impacts communication, credibility with developers, and management of breaking changes in the method.

Options considered:

• Semver (x.y.z) — GitHub standard, clear maturity signal
• Calver (YYYY.MM) — suited for continuous release products
• No versioning — just commits

Decision

Adopt semver (x.y.z) for SOFIA.

• Major (x): incompatible change in artifact structure or persona model
• Minor (y): new artifact, new guide, method enrichment
• Patch (z): corrections, clarifications, typos

v1.0.0 = first public release.

Consequences

• Each GitHub release carries a semver tag
• CHANGELOG.md follows the same format as Katen
• Breaking changes in templates or conventions must be documented in release notes
• The README displays the version badge

ADR-002 — Two levels of steering: product roadmap + assistant backlog

Status: Superseded Superseded by: ADR-007 (Ownership by roadmap) Date: 2026-03-30 Author: Mira

Context

The orchestrator steers multiple products with multiple assistants. Two distinct needs:

• Know the status of each product (versions, features, milestones)
• Know the status of each assistant (current tasks, blockers)

The initial approach (analyse-voix-convergence.md §6.2) planned a single roadmap.md per workspace with two sections (open items + deliverables). The problem: a product roadmap is shared across multiple assistants (Mira, Nora (UX), Axel (dev) all work on Katen), whereas a backlog is local to an assistant.

Decision

Separate into two artifacts:

Product roadmap — shared/roadmap-{product}.md

• Lives in the shared bus (shared/)
• Driven by the orchestrator
• Read by all relevant assistants
• Contains: versions, features, milestones, structural decisions
• Examples: shared/roadmap-katen.md, shared/roadmap-sofia.md, shared/roadmap-convergence.md

Assistant backlog — backlog.md at the root of each workspace

• Local to the workspace
• Managed by each persona
• Contains: open items with source:, deliverables with cible:
• 5 normalized statuses: done, running, ready, todo, blocked
• ↔ markers for cross-voice convergences

Session protocol:

• Opening: scan relevant shared/roadmap-*.md + own backlog.md + inbox shared/
• Closing: update own backlog.md

Consequences

• Each persona creates their own backlog (not a third party doing it for them)
• Product roadmaps do not live in product repos — they are in the shared bus
• Convergence parses both types: backlog.md per workspace + shared/roadmap-*.md
• SOFIA templates provide backlog.md and product-roadmap.md

Note (v0.2.2)

The per-persona backlog system was removed in v0.2.2 (01/04/2026). Backlogs are replaced by product roadmaps with @owner markers. Arbitration remains with the orchestrator, tracking goes through roadmaps in shared/. See ADR-007.

ADR-003 — Internationalization strategy

Status: Accepted Date: 2026-03-30 Author: Mira

Context

SOFIA is an open source product with international reach (GitHub, dev community). Existing content is mostly in French (method, Katen examples, feedback). The target audience is global.

i18n in a git documentation repo has a structural cost: content duplication, translation synchronization, choice of source language, impact on contributions.

Options

A — English first, French as override

• methode/, claude-code/, outillage/ in English (source language)
• i18n/fr/ contains French translations (same tree structure)
• A single source of truth, English
• Existing French content must be translated — significant initial effort

B — French first, English as override

• Existing content stays in French (no migration)
• i18n/en/ contains English translations
• Less initial effort, but French as source limits international contributions

C — Per-language root folders

• en/methode/, fr/methode/
• Standard approach (React docs, Kubernetes docs, Docusaurus)
• Tree duplication, manual sync between the two
• Works well with doc tooling (build.py, static site)

D — File suffix

• artifacts.fr.md, artifacts.en.md side by side
• Easy diffing, no tree duplication
• Noisy tree beyond 2 languages

Decision

Mixed option adopted — French as source language, English added in v0.4.0.

• Target structure: core/fr/ + core/en/ (paired folders)
• French remains the source language — it is the orchestrator's voice
• Partial translation tolerated: English-speaking users are the testers (arc42 model)
• File names in the language of the content (no .fr.md suffix)
• The orchestrator does not test English — English-speaking early adopters do
• Timing: i18n in v0.4.0, after v0.3.0 publication. Not before feedback.

Consequences

• core/ will be renamed core/fr/ in v0.4.0, core/en/ created in parallel
• English contributions are welcome from v0.4.0
• Translation is a community effort, not a publication prerequisite
• The risk of voice dilution is accepted for English — French is authoritative in case of divergence
• Methodological reference: arc42 model (DE source, EN community-translated)

ADR-004 — Multi-platform AI support

Status: Superseded (by ADR-010) Date: 2026-03-30 Author: Mira

Context

SOFIA is designed and tested on Claude Code (Anthropic). The method relies on specific mechanisms: CLAUDE.md, personas via system prompt, isolation by workspace, sessions with persistent context.

Other platforms offer comparable or emerging capabilities:

• Codex (OpenAI) — autonomous code agents
• Gemini (Google) — long context, multimodal
• Mistral (Le Chat) — open models, compatible API
• Cursor, Windsurf, Aider — augmented IDEs with rules files

The question: does SOFIA remain specific to Claude Code, or does it become a generic multi-agent AI orchestration method?

Options

A — Claude Code only

• SOFIA = method for Claude Code, period
• Simpler, deeper, more credible on one tool
• Limits the audience

B — Common core + adaptation guides

• Extract generic principles (personas, isolation, bus, sessions)
• One guide per platform mapping the concepts (CLAUDE.md → .cursorrules, etc.)
• Analysis phase required on each platform
• Significant effort but maximum reach

C — Complete abstraction

• The method mentions no specific tool
• Too abstract, loses the concreteness that provides value

Decision

Option B adopted — common core in sofia + separate repos per platform.

Each adaptation repo:

• References sofia for generic principles (personas, isolation, bus, sessions)
• Documents the concept mapping (CLAUDE.md → platform equivalent)
• Contains its own templates, examples, getting started guide
• Independent versioning (semver)

Timeline: v0.3.0 publication first (April 2026), user feedback, then v0.5.0 multi-platform. First Mistral test planned summer 2026. Analysis phase before implementation. No multi-platform work before real feedback on v0.3.0.

Open items:

• Who: is a dedicated persona needed or is it Mira + orchestrator testing work?
• Extractable core: identify in sofia what is generic vs what is Claude Code-specific — prerequisite before any adaptation
• Contribution: each adaptation repo can live independently (maintained by the platform community)

Consequences

• sofia must clearly separate the method core from the Claude Code implementation (structurally or through documentation)
• Each adaptation requires a real test, not a theoretical mapping — time budget required
• The naming sofia-{platform} creates a coherent family of repos under the oxynoe-dev org

ADR-005 — Instance marker sofia.md

Status: Accepted Date: 2026-04-05 Author: Mira

Context

SOFIA is a method applied to concrete projects (instances). There needs to be a way to know whether a repository is a SOFIA instance, which version of the method it uses, and how to link it to the sofia/ repo.

Options considered:

• Implicit convention — no marker, structure is guessed
• JSON config file — structured but unreadable without tooling
• Simple markdown file — readable by humans and LLMs

Decision

A sofia.md file at the root of each instance. Contains: method version, link to the voice repo, last synchronization date, list of active personas. Markdown format (not JSON) — readable by humans and LLMs. The file is versioned with the project.

Consequences

• Each instance is self-descriptive
• Convergence can scan sofia.md files to inventory instances
• The SOFIA template provides a pre-filled sofia.md
• Marker update is manual (no automatic sync)

ADR-006 — Pre-publication core/ isolation

Status: Accepted Date: 2026-04-05 Author: Mira

Context

SOFIA is preparing for publication (v0.3.0). The current structure mixes the method core (principles, personas, orchestration...) with the Claude Code implementation and user documentation. To accommodate PRs and contributions, there needs to be a clear boundary between what is the method (stable, provider-agnostic) and what surrounds it.

Decision

Restructure voix/ with a core/ directory containing only the method core: principles, personas, friction, isolation, orchestration, traceability, artifacts, instance, duties. The Claude Code implementation stays in claude-code/. Templates in core/templates/. Documentation in doc/. core/ is the part that does not change between providers — it is the kernel that voix-mistral, voix-gemini repos reference.

Consequences

• The core/ structure is a contract — any change in core/ is a method change (minor or major in semver)
• Contributions can touch doc/ without impacting the core
• Prerequisite for i18n (v0.4.0: core/fr/ + core/en/)
• Quality gate: core/ must be stable before publication

ADR-007 — Ownership by roadmap

Status: Accepted Date: 2026-04-05 Author: Mira

Context

The initial system (ADR-002) planned two levels: product roadmaps in shared/ + per-persona backlogs in each workspace. In practice, backlogs duplicated roadmaps, created confusion about the source of truth, and added overhead to session boot/closing. The v0.2.2 planning overhaul removed all 7 backlogs.

Decision

Remove persona backlogs. Each roadmap item carries an @owner marker (e.g., @mira, @axel). The persona filters the roadmap by their @owner at session opening. The orchestrator remains the owner of roadmaps. Statuses are normalized: [done], [running], [ready], [todo], [blocked]. Supersedes ADR-002.

Consequences

• Session boot and closing simplified (no more backlog to maintain)
• A single source of truth per product (the roadmap)
• Filtering by @owner replaces the local backlog
• SOFIA templates are updated (backlog removed)
• Ownership mapping: Orchestrator (Katen), Mira (SOFIA, Convergence, Oxynoe Site, Oxynoe IS), Lea (recherche) (Research), Winston (redacteur) (Editorial)

ADR-008 — Core / Protocol / Provider restructuring

Status: Accepted Date: 2026-04-06 Author: Mira

Context

The core/ directory mixed two natures of content: the method invariants (principles, personas, friction, duties) and the interface contract (artifacts, conventions, traceability, isolation, orchestration, instance). Likewise, claude-code/ lived at the root even though it is a replaceable implementation.

This confusion blurred the boundary between what is portable and what is not. In preparation for publication (v0.3) and multi-provider support (v0.5), the repo structure needs to reflect the conceptual model.

Decision

Restructure voix/ into three explicit layers:

Core — The invariants. Principles, personas, friction, duties. What does not change when changing tools. Templates: persona + 7 archetypes.

Protocol — The interface contract. Artifacts, conventions, traceability, isolation, orchestration, instance. Files, not APIs. Git, not databases. This is what makes SOFIA portable. Templates: note, review, feature, adr, session, roadmap, team-orga, voix-instance.

Provider — The concrete implementation. Claude Code today (claude-md, memory, sessions, hooks). Replaceable without touching core or protocol. Templates: claude-md, workspace scaffold.

voix/
├── core/              ← invariants + persona templates
├── protocol/          ← interface contract + bus templates
├── provider/
│   └── claude-code/   ← implementation + provider templates
└── doc/

Alternatives considered

1. Keep the flat structure (core/ + claude-code/) — Simple but conflates two abstraction levels. The question "what is portable?" has no obvious answer in the structure.
2. Two layers (method/ + binding/) — Does not explicitly name the protocol, which is the key portability layer.
3. Four layers (core/ + protocol/ + provider/ + tooling/) — Separate templates into tooling/. Rejected: templates embody their layer, separating them breaks coherence.

Consequences

• Internal paths change — all links updated (doc, workflows, CLAUDE.md, README)
• Historical ADRs (003, 006) are not modified (convention: history is not corrected)
• The CHANGELOG records the change as an internal breaking change
• The structure is ready for provider/mistral/ in v0.5 without further restructuring
• Templates are distributed within their layer, not centralized — a contributor immediately knows which layer a template belongs to

Origin

Proposal from Sofia (gardienne) (graphism session 2026-04-05) identifying the three levels: "Core — the invariants. Protocol — the interface contract. Provider — the concrete implementation." Validated and implemented by Mira, arbitrated by the orchestrator.

ADR-009 — Instance layer, repo restructuring and Sofia's position

Status: Accepted Date: 2026-04-10 Author: Mira Partially supersedes: ADR-008 (adds a layer, restructures the repo)

Context

ADR-008 structured the repo into three layers: Core (invariants), Protocol (interface contract), Provider (implementation). The "four layers" alternative had been rejected — the need was not clear.

Three observations change the situation:

1. Instance personas are not in the core. Archetypes (architect, dev, strategist...) are reference models. Concrete instance personas (Mira, Axel, Marc (strategie)...) are specific to the orchestrator. This is neither core, nor protocol, nor provider.

2. Archetypes are not invariants. An orchestrator builds their personas from their tension axes, not by copying a template. Archetypes show what a persona looks like by role — they inspire, they do not scaffold. This is not core material.

3. Sofia must be outside the instance to audit it objectively. Sofia lives in the product (core/sofia.md) AND in the instance (workspace experiments/sofia/). This is a structural conflict: she is both judge and party. The same pattern as Rodin applies — exteriority is the condition of objectivity.

Decision

Four layers in the product repo

sofia/
├── core/              ← invariants (principles, friction, duties, persona anatomy, sofia)
├── protocol/          ← the rules (artifacts, conventions, traceability, isolation, orchestration)
├── instance/          ← references for building an instance
│   ├── archetypes/    ← persona models by role (to draw inspiration from, not to copy)
│   ├── artifacts/     ← what a note, a review, a session look like...
│   └── examples/      ← katen/ (how it manifests in the field)
├── provider/          ← implementation (claude-code)
└── doc/               ← documentation, feedback, patterns, ADR

Core = what never changes. Principles, friction, duties, persona anatomy. If you change this, you change the method.

Protocol = the rules an instance must follow. Conventions, naming, isolation, orchestration. The contract.

Instance = the references for building your own instance. Persona archetypes, reference artifacts (what a note, a review, a session look like), and a complete field example (Katen — snapshot of a living instance with shared/, workspaces, conventions). You draw inspiration from it, you do not copy it.

Provider = the implementation for a given provider. Replaceable without touching the rest.

Migration plan

Migrates to instance/archetypes/

Migrates to instance/examples/katen/

Minimal snapshot of an instance — shows the complete structure with the minimum needed to understand the pattern. Two workspaces (archi + dev), a functional bus, one roadmap.

instance/examples/katen/
├── sofia.md                              ← instance marker
├── shared/
│   ├── conventions.md                    ← instance conventions
│   ├── roadmap-katen.md                  ← 1 roadmap (fake, 2-3 versions)
│   ├── notes/
│   │   ├── note-mira-xyz-axel.md         ← 1 active note
│   │   └── archives/
│   │       └── note-axel-abc-mira.md     ← 1 archived note
│   ├── review/
│   │   ├── review-adr-001-mira.md        ← 1 active review
│   │   └── archives/
│   │       └── review-spec-axel.md       ← 1 archived review
│   └── orga/
│       ├── team-orga.md
│       └── personas/
│           ├── persona-mira.md
│           └── persona-axel.md
├── architecture/                         ← architect workspace
│   ├── CLAUDE.md
│   └── sessions/
│       └── 2026-04-10-1-mira.md          ← 1 session
└── dev/                                  ← dev workspace
    ├── CLAUDE.md
    └── sessions/
        └── 2026-04-10-1-axel.md          ← 1 session

Migrates to instance/artifacts/

Stays in place

Directories removed after migration

• core/templates/ (empty — archetypes and persona.md migrated)
• protocol/templates/ (empty — formats migrated)
• provider/claude-code/templates/ (empty — CLAUDE.md migrated)
• doc/examples/ (empty — migrated to instance/examples/)

Sofia's position

Sofia remains in the product (core/sofia.md). She has no workspace in instances. She intervenes from the outside to:

• Install a new instance (onboarding)
• Audit an existing instance (conformity verification)
• Set up an audit instance (mirror challengers)

Two types of instances

Alternatives considered

1. Keep 3 layers, no instance/ in the repo — Archetypes stay in core/templates/, examples in doc/examples/. The boundary "invariant vs instanciation reference" remains implicit. Rejected: the confusion has already caused placement errors.
2. instance/ as a scaffolding kit (templates to copy) — Name the directory "templates" and present files as copy-paste models. Rejected: SOFIA is a method to internalize, not a kit to deploy mechanically. Archetypes and formats are references — you draw inspiration from them, you build your own.
3. Leave Sofia in the instance — Structural conflict of interest documented. Rejected.
4. Put a living instance in the product repo — Conflates the model and the deployment. instance/examples/katen/ is a snapshot that shows the complete structure of an instance, but does not live — the real instance lives in its own repo and evolves independently.

Consequences

• The repo structure changes — internal links to update
• core/templates/ and protocol/templates/ disappear
• arch-sofia.md goes from 3 to 4 layers in the repo
• Sofia no longer has a workspace in experiments/
• The audit instance concept is formalized
• Contributors immediately know where to look: invariants → core/, rules → protocol/, instanciation references → instance/, implementation → provider/
• The mental model changes: you do not "deploy" SOFIA, you understand it and build your instance

Origin

Rodin sessions (09-10/04): identification of the meta persona, Nora×Luz merger, hidden condition. Orchestrator discussion (10/04): separation rules/references, archetype positioning, SOFIA as a method not a kit.

ADR-010 — Multi-platform via binding layer

Status: Accepted Date: 2026-04-16 Author: Aurele Supersedes: ADR-004

Context

ADR-004 planned separate repos per platform (sofia-mistral, sofia-gemini, etc.), each referencing the sofia repo for generic principles.

In the meantime, v0.3.2 introduced two evolutions that make this approach obsolete:

1. The binding/ layer (cf. ADR-012) separates the protocol semantics (protocol/) from its concrete binding (binding/filesystem/). What was planned as an external mapping in an adaptation repo is now an internal layer of the repo.
2. The provider/ layer already hosts the Claude Code implementation in provider/claude-code/. The structure is ready for provider/mistral/, provider/gemini/ etc. without restructuring.

The "separate repos" strategy scatters the method and complicates coherence. The alternative is to keep everything in the same repo, with provider adapters.

Decision

Multi-platform in the same repo, not in separate repos.

sofia/
├── core/              ← invariants (identical regardless of provider)
├── protocol/          ← H2A semantics (identical)
├── binding/           ← protocol binding(s)
│   └── filesystem/    ← current binding
├── provider/          ← adapters per provider
│   ├── claude-code/   ← reference implementation
│   ├── mistral/       ← Mistral adapter (target v0.4)
│   └── ...
├── instance/          ← instanciation references
├── canvas/            ← inspiration tools
└── doc/

Core + Protocol = the portable kernel. Mentions no provider.

Binding = how the protocol materializes (filesystem today, API/DB tomorrow). Potentially multiple bindings.

Provider = how a specific provider executes instructions (CLAUDE.md, MISTRAL.md, hooks, memory). One adapter per provider.

The binding/provider distinction is the key:

• binding/ answers "how artifacts are stored and audited"
• provider/ answers "how the persona receives its instructions and persists its context"

Alternatives considered

1. Separate repos (ADR-004) — Scatters the method, complicates inter-provider coherence, creates cross-versioning problems. Superseded.
2. Everything in provider/ — Merge binding and provider into a single directory per provider. Rejected: the semantic distinction is real (a filesystem is shared between providers, a CLAUDE.md is not).

Consequences

• The sofia-mistral, sofia-gemini repos will not be created
• ADR-004 is superseded
• Each provider adapter is autonomous (an orchestrator can mix providers per persona)
• The portable kernel (core/ + protocol/) remains the single reference
• v0.4 (multi-platform) is done by adding a provider/mistral/, not by creating a repo

Origin

Organic emergence during the v0.3.2 overhaul: the extraction of binding/ and the H2A formalization made explicit the structure that renders separate repos unnecessary.

ADR-011 — H2A Protocol (Human-to-Assistant)

Status: Accepted Date: 2026-04-16 Author: Aurele

Context

Until v0.3.1, human-assistant coordination was described in a diffuse manner: conventions in protocol/, principles in core/, operational rules in documentation. There was no unified formalization of the coordination protocol.

Three observations motivated the formalization:

1. Missing positioning. MCP (Anthropic) covers agent-tools, A2A (Google) covers agent-agent. The human-assistant layer had neither a name nor a spec.
2. Under-specified friction. Markers existed but without theoretical lineage, without formal resolutions, without a mechanism to mitigate orchestrator opacity.
3. Ambiguous auditability. No clear distinction between what an audit tool can verify mechanically (protocolar) and what requires judgment (observational).

Decision

Formalize H2A as an organizational protocol in protocol/h2a.md, with satellite documents (friction.md, exchange.md, contribution.md).

Protocol structure

5 invariants — constitutive properties without which H2A is no longer H2A:

1. Constitutive friction
2. Human arbiter
3. Isolation
4. Traceability
5. Residual opacity (structural limitation, not a capability)

7 entities — Instance, Space, Persona, Orchestrator, Exchange, Friction, Contribution. Conceptual model in core/modele.md.

9 operations — from openSession() to reportPattern(). Defined in semantics, not in wire format.

2 formalization layers:

• Protocolar — computational verification, deterministic, automatable
• Observational — inferential verification, semantic judgment, best-effort

Key elements

PXP resolutions — 4 epistemic gestures (ratified, contested, revised, rejected) qualifying the outcome of each friction. Inspired by Mestha et al. (2025).

reportPattern() — operation to mitigate orchestrator opacity. Detection of thematic convergence in rejections, 3 argued hypotheses, mandatory qualification with asymmetric burden of proof.

Inter-session mutability — a resolution can evolve in a subsequent session, with traceable reference (ref:).

Lineage from principles to invariants — the invariants derive from principles (core/) but do not cover all of them. Principles guide the entire method, invariants only pertain to the protocol.

Terminology

Keywords per RFC 2119 (MUST, SHOULD, MAY).

Alternatives considered

1. No formalization — Keep diffuse conventions. Rejected: auditing and multi-instance require a stable spec.
2. Technical protocol from the start — Define a wire format (JSON, endpoints). Rejected: premature. The protocol is organizational, the technical implementation will come when the need is real.
3. Merge with core — Put H2A invariants in core/principes.md. Rejected: the invariants pertain to the exchange protocol, not the entire method.

Consequences

• protocol/h2a.md becomes the reference document for coordination
• protocol/friction.md, exchange.md, contribution.md specify the entities
• Auditing is founded on the protocolar/observational distinction
• The complete document (positioning, discussion, open questions) is in doc/h2a-proposal.md
• Future implementations (API, DB) can be H2A-conformant as long as they respect the semantics

Theoretical lineage

Origin

v0.3.2 overhaul: convergence between the formalization of principles (core/), the review of the SOFIA article (note-equipe-reflexions-h2a.md), and the need for multi-instance auditability.

ADR-012 — Extraction of the binding layer

Status: Accepted Date: 2026-04-16 Author: Aurele

Context

Until v0.3.1, binding tools (audit-instance.py, create-instance.py, tests) lived in protocol/tools/. Rendering conventions (how to write a friction in Markdown, how to structure a session summary) were mixed with protocol semantics in protocol/.

This mixing caused two problems:

1. Semantics/binding confusion. "Friction carries 5 dimensions" (protocol) and "friction is a Markdown line with symbol + keyword + initiative" (binding) coexisted in the same documents. Impossible to tell what is portable and what is tied to the filesystem.
2. Multi-binding blockage. If H2A is implemented tomorrow via a REST API or a database, the tools and rendering conventions change, but the semantics do not. Having everything in protocol/ forces touching the protocol to change the binding.

Decision

Extract a separate binding/ layer from the protocol.

sofia/
├── protocol/           ← semantics (what)
│   ├── h2a.md          ← invariants, operations, layers
│   ├── friction.md     ← dimensions, markers, resolutions
│   ├── exchange.md     ← artifacts, sessions, frontmatter
│   └── contribution.md ← direction, types
├── binding/            ← materialization (how)
│   ├── implementation.md  ← stack, rendering conventions, operations mapping
│   └── filesystem/        ← tools for the current binding
│       ├── audit-instance.py
│       ├── create-instance.py
│       ├── conventions.md (template)
│       └── tests/
└── ...

Protocol answers "what is a friction, what is a session, what is an artifact" — in terms of semantics, not format.

Binding answers "how it materializes" — Markdown + frontmatter + git + directories. This is where rendering conventions, the mapping of operations to concrete actions, and audit/scaffolding tools live.

The document binding/implementation.md contains an explicit "protocol vs binding" table for each element.

Alternatives considered

1. Everything in protocol/ — Simple but conflates two levels. When writing "friction is a Markdown line", that is an implementation choice, not a protocol one. Rejected.
2. Tools in a root-level tools/ directory — Separates scripts but not rendering conventions. Rejected: the problem is conceptual, not merely organizational.
3. One directory per binding (filesystem/, api/, bdd/) — Premature. The filesystem binding is the only one that exists. The binding/filesystem/ structure is ready to accommodate other bindings when they become real.

Consequences

• protocol/ no longer contains rendering conventions or scripts
• binding/implementation.md is the reference document for the current binding
• Tools (audit, create-instance) live in binding/filesystem/
• The binding:filesystem tag on artifact canvases distinguishes what is tied to the binding
• A future alternative binding (API, DB) would live in binding/api/ etc. without touching the protocol
• ADR-008 (Core/Protocol/Runtime) remains valid — binding/ is a complementary layer, not a replacement

Origin

v0.3.2 overhaul: the formalization of H2A (ADR-011) made visible the semantics/binding mixing in protocol/. The separation became necessary for the protocol to remain portable.

ADR-013 — Technical identifiers in English

Status: Accepted Date: 2026-04-16 Author: Aurele Review: @solene (2026-04-16) — ratified all 4 open items

Context

The H2A protocol's technical identifiers (friction markers, resolution tags, directions, contribution types, frontmatter fields) are currently in French. They traverse 3 layers: protocol/ (spec), binding/ (Python, JSON), dashboard (HTML/JS).

The protocol is intended for publication in English. Translating identifiers later implies a simultaneous refactoring across the protocol, the parser, the JSON schema, the dashboard, instance conventions, and historical sessions.

Decision

Technical identifiers switch to English. Content (descriptions, documentation) remains in French as long as the protocol is not translated.

Friction markers

Resolution tags

Directions

Contribution types

Artifact frontmatter fields

Initiative tags

Resolved items (review @solene 2026-04-16)

1. juste → sound — exact Toulmin term. correct implies objective truth, sound captures argumentative soundness. Ratified.
2. faux → refuted — argumentative act (rebuttal), not truth judgment. Maintains the argumentative register of other markers. Eliminates boolean collision. Ratified.
3. Backward compatibility — bilingual parser (FR+EN) during transition. The FR→EN mapping must be documented explicitly in the parser (not a silent alias). Ratified.
4. matiere → substance — substantive contribution, argumentation philosophy register. material too physical, content too generic, input too procedural. Ratified.

Impact

Consequences

• Identifiers are stable for the English publication of the protocol
• The parser accepts FR and EN during the transition
• No history rewriting — historical sessions remain in French
• The dashboard displays EN labels (or translated per locale, out of scope)

ADR-014 — Rename implementation/ → binding/ and runtime/ → provider/

Status: Accepted Date: 2026-04-20 Author: Aurele

Context

SOFIA's 5-layer architecture uses implementation/ (layer 3) and runtime/ (layer 4). These names create confusion:

• "Implementation" is too generic — it collides with the English word used in prose ("provides an implementation for..."). It doesn't convey what the layer actually does: materializing the protocol into a specific persistence strategy (filesystem, API, database).
• "Runtime" is ambiguous — it suggests execution time, not the AI provider that executes the persona. It collides with "runtime behavior" (generic) vs "the runtime/ directory" (SOFIA-specific).

More importantly, the two layers represent orthogonal axes:

• Axis 1: how the protocol materializes (files, endpoints, tables) — a binding
• Axis 2: which AI tool executes the persona (Claude Code, Mistral, Gemini) — a provider

The current names don't make this orthogonality visible.

Decision

• implementation/ → binding/
• runtime/ → provider/

Rationale: "binding"

The term binding is standard in protocol specifications for designating the materialization of an abstract spec into a concrete transport or format:

• CloudEvents (CNCF): bindings/http-protocol-binding.md, bindings/kafka-protocol-binding.md
• AsyncAPI: dedicated asyncapi/bindings repository, one subdirectory per protocol
• WSDL/SOAP (W3C): the <binding> element bridges <portType> (abstract) to a concrete protocol
• OASIS AMQP: dedicated AMQP-BINDMAP technical committee for protocol bindings
• Dapr (Microsoft/CNCF): bindings/ as a core building block
• Kubernetes: ServiceBinding specification

CloudEvents is the closest structural precedent: specification (spec.md) / bindings (bindings/) / SDKs (per-language).

Rationale: "provider"

The term provider is standard for a pluggable implementation of a capability:

• Terraform / Pulumi / Crossplane: providers supply concrete resources for a target platform
• ADO.NET: data providers per database engine
• SOFIA itself: already uses "provider" in prose ("Claude Code today, Mistral tomorrow")

Alternatives considered

Consequences

• All internal references (paths, layer names, SVG) updated in this commit
• The file binding/implementation.md keeps its name — it describes the filesystem binding specification. A future rename to binding/filesystem.md may follow when a second binding appears.
• doc/adr/adrs.md index updated
• doc/concepts/architecture.md updated (layer names, tree diagram, decision table)
• 3 SVG updated (arch-sofia, fig-structure-repo, fig-mcd-h2a)
• No breaking change for instances — instance conventions reference protocol semantics, not directory names