Implementation

How H2A is implemented today — and how it could be implemented tomorrow.

Principle

H2A defines the semantics of interactions (entities, invariants, protocol/observational layers). This document describes the current implementation. A different implementation would be H2A-conformant as long as it respects the semantics defined in h2a.md, friction.md, contribution.md, and exchange.md.

Current implementation

Stack

Traceability conventions

Commits (recommended):

{persona}: {short summary} ({date})

One commit per session.

Session summaries:

{space}/sessions/{YYYY-MM-DD}-{HHmm}-{persona}.md

At each closure, the persona creates a new file. The HHmm is the closure time (not the boot time). A long session with multiple closures produces multiple files.

Instance structure

Scaffolding is minimal — only elements necessary for the protocol are created at initialization. The internal organization of shared/ (subdirectories, artifact naming conventions, archiving) is an instance convention, not standard implementation.

instance/                        ← scaffolding (create-instance)
├── sofia.md                     ← instance marker
├── shared/                      ← shared space (exchange bus)
│   ├── conventions.md           ← instance-specific conventions
│   └── orga/                    ← team organization
│       ├── personas/            ← persona files
│       └── contextes/           ← contexts per persona-product
├── {space}/                     ← one per persona
│   ├── CLAUDE.md                ← persona instructions (provider)
│   └── sessions/                ← session summaries
└── ...

The protocol requires shared/ as the sole channel and artifacts with frontmatter. How the instance organizes its artifacts in shared/ (subdirectories, naming, archiving) is a local decision documented in conventions.md.

Repo ownership (MAY)

When an instance spans multiple repositories, conventions.md MAY declare a ## Repo ownership section mapping external repo paths to persona owners.

## Repo ownership

| Repo | Path | Owner |
|------|------|-------|
| product-repo | doc/architecture/ | @architect |
| product-repo | (rest) | @dev |

This is useful when personas from the same instance work in different parts of the same external repo. The workspace field in persona files covers the instance-internal space; repo ownership covers external repos.

Installing the protocol on a persona

The H2A protocol is installed via the context (shared/orga/contextes/contexte-{persona}-{product}.md), not via the persona file. The persona file defines the role (instance-agnostic). The context installs the instance rules.

Each context MUST contain an ## H2A Protocol section that:

• Points to shared/conventions.md (read at first boot, reread before each artifact and closure)
• Recalls the mandatory session summary sections (Produced, Decisions, Shared notes, Open)
• Recalls the observational sections (Orchestrator friction SHOULD, Flow MAY)
• Recalls the commit convention
• Contains the inline friction template — the exact expected format, directly visible in the context

Without this section, the persona will not trace friction — this is the most common prescription/usage gap.

Inline friction template (to include in each context):

Friction format: {symbol} [{marker}] {description} — [{initiative}] → {resolution}
Markers: ✓ [sound], ~ [contestable], ⚡ [simplification], ◐ [blind_spot], ✗ [refuted]
Initiative: [persona] or [PO]
Resolution (SHOULD): → ratified, → contested, → revised, → rejected
Lineage: if amending a prior friction, add (ref: {source-id}/{index})

The template is a safety net — the persona has the format in view when producing, without rereading an external file.

Frontmatter

Every artifact deposited in the shared space carries a YAML frontmatter. No accents in values.

Artifacts:

---
from: persona-emitter
to: persona-recipient
nature: signal           # signal | question | request | response
status: new              # new | read | done
date: YYYY-MM-DD
ref: artifact-identifier # SHOULD when nature = response
---

The ref field links a response to its source artifact. The identifier is the filename without extension (e.g., note-aurele-localisation-doc-site-livia). For cross-instance artifacts, the instance-source field indicates the originating instance.

Sessions:

---
persona: persona-name
date: YYYY-MM-DD
session: "HHmm"
---

Archiving

When an artifact moves to status: done, it is moved to archives/ in the parent directory.

Status lifecycle

Retrocompat: the parser also accepts FR values (nouveau, lu, traite).

Artifact resolution

When an artifact is processed, each point SHOULD carry a resolution tag in the document body (not in the frontmatter — an artifact often contains multiple points).

Convention: the recipient annotates each point with → ratified, → contested, → revised, or → rejected before archiving.

Example:

## Proposition A
→ ratified

## Proposition B
→ rejected (short justification)

## Proposition C
→ revised (detail on what changes)

Retrocompat: the parser also accepts FR tags (ratifie, conteste, revise, rejete).

Friction in session summaries

Section ## Orchestrator friction (SHOULD — see exchange.md §Sessions, observational layer).

Each line carries the dimensions defined in friction.md, rendered as:

## Orchestrator friction
- [marker] description — [initiative] → resolution

Markers: rendered as bracketed keywords + visual symbol in instance conventions.

Retrocompat: the parser also accepts FR brackets ([juste], [angle-mort], [faux]).

Visual symbols (✓/~/⚡/◐/✗) are an instance convenience. Bracketed keywords are authoritative for audit.

Initiative: [persona] or [PO] — who initiated the friction subject.

Resolution: epistemic gesture tag after the arrow →. See protocol/friction.md §Resolution.

The resolution tag is set per friction point, not per section.

Example:

## Orchestrator friction
- ✓ [sound] the Toulmin mapping illuminates without constraining — [PO] → ratified
- ~ [contestable] the Toulmin mapping is suggestive, not established — [PO] → revised
- ◐ [blind_spot] scaffolding absent from the Böckeler review — [aurele] → ratified

Lineage (antecedent dimension)

When a friction amends a prior friction (see protocol/friction.md §Lineage), the antecedent dimension is materialized by a ref: field at the end of the line:

- ✓ [sound] the protocol/observational distinction covers the case — [aurele] → ratified (ref: 2026-04-10-1430-aurele/3)

Format: ref: {source-id}/{index} where:

• {source-id} = filename (without extension) — session summary or artifact
• {index} = friction position in the source file (1-based, order of appearance)

Implementation rules:

• The parser MUST follow ref: links and propagate the resolution from the last link to the source friction.
• A friction referenced by a ref: does not appear in the open frictions list if the referencing link carries a resolution.
• Counters count the logical friction once, with the original marker and the final resolution.

The exchange and emitter dimensions are implicit: the exchange is the current session, the emitter is the persona authoring the summary.

reportPattern in session summaries

Section ## reportPattern (MAY — observational layer for the observation, protocol layer for the counter).

The persona records the trigger and the orchestrator's choice:

## reportPattern
- Theme: [theme] — N rejected frictions (sessions YYYY-MM-DD, ...)
- Choice: LLM error | conviction | resistance
- Justification: ...

The audit counts triggers and the distribution of choices (protocol counter).

Contribution in session summaries

Section ## Flow (MAY — see exchange.md §Sessions, observational layer).

Each line carries the dimensions defined in contribution.md, rendered as:

## Flow
- {direction}:{type} — description

Direction: H (human brings) or A (assistant brings). Type: substance, structure, contestation, decision.

Counting (optional): a summary line at the end of the section.

Example:

## Flow
- H:substance — Böckeler article, request for opinion
- A:substance — scaffolding lineage absent from Böckeler
- A:structure — three levels of harness/SOFIA complementarity
- H:decision — keep keyword notation

H:2 (substance 1, decision 1) | A:2 (substance 1, structure 1)

The session dimension is implicit: it is the current session.

Operations — filesystem implementation

Mapping of H2A operations (see protocol/h2a.md) to the current implementation.

Manual = the orchestrator triggers with an explicit gesture. Automatic = the persona produces at session closure, the orchestrator validates.

The persona MUST NOT close on its own or deposit an artifact without orchestrator instruction.

Tooling

What is implementation vs protocol

Perspectives

HTTP API

H2A could be implemented as a REST API:

• Each entity (Instance, Space, Persona, Exchange, Friction, Contribution) becomes a resource
• YAML frontmatter becomes JSON schemas
• Statuses (new → read → done) become state transitions
• Audit becomes a verification endpoint

Database

Session summaries, artifacts, and friction markers could live in a relational or document database. Git history would be replaced by an event log.

MCP / A2A interoperability

H2A covers the human-assistant layer. MCP and A2A cover the agent-tools and agent-agent layers. A complete system could combine all three:

• H2A for human-assistant coordination
• MCP for resource access by assistants
• A2A for inter-assistant coordination (if the human routing invariant is relaxed)

Wire format

If H2A evolves toward a technical protocol, a wire format (JSON, protobuf, etc.) and an interoperability spec will be needed. This is not in the current scope.

Audit rules — binding/filesystem

Reference for all checks performed by analysis/cli/probe.py.

Check ID taxonomy

Format: {level}{category}{number}

Severity

Protocol checks

Protocol Structure (PS)

Protocol Personas (PP)

Protocol Artifacts (PA)

Global checks on ALL .md files in shared/ (excluding conventions.md, roadmap-*.md, orga/, audits/).

Protocol Format (PF)

Artifact checks

Each declared artifact type gets 5 standard checks. Add --artifacts notes,reviews,features to control which types are audited.

Artifact Note (AN)

Artifact Review (AR)

Artifact Feature (AF)

Other artifact types (dynamic)

Any type declared in ## Artifact types of shared/conventions.md gets the same 5 checks (A{X}1-A{X}5) with a dynamic prefix. Common optional types:

These are not protocol — they are instance conventions. An instance that doesn't use ADRs or team-orga simply doesn't declare them.

Instance checks

Instance Structure (IS)

Instance Naming (IN)

Instance Roadmap (IR)

Conventions documented in shared/conventions.md §Roadmaps.

Artifact types

By default, the audit scans notes and reviews in shared/. An instance can declare additional artifact types in shared/conventions.md using a ## Artifact types section:

## Artifact types

| Type | Directory | Naming | Extra fields |
|------|-----------|--------|--------------|
| notes | shared/notes/ | `note-{subject}-{author}.md` | |
| reviews | shared/review/ | `review-{subject}-{author}.md` | subject |
| features | shared/features/ | `feature-{name}.md` | |
| adr | shared/adr/ | `adr-{number}-{title}.md` | |
| team-orga | shared/orga/ | `team-orga.md` | |

The --artifacts flag lets the user override which types are audited:

# Audit only protocol checks + notes and reviews (default)
python analysis/cli/probe.py /path/to/instance

# Audit with features included
python analysis/cli/probe.py /path/to/instance --artifacts notes,reviews,features

# Protocol checks only — skip all artifact and instance checks
python analysis/cli/probe.py /path/to/instance --protocol-only

When --protocol-only is set, all artifact checks (AN1-AN5, AR1-AR5, AF1-AF3) and instance checks (IS1-IS4, IN1, IR1-IR8) are skipped.

Phase 2 — Exchanges & friction

Phase 2 scans all .md files in the declared artifact directories and extracts:

• Exchange matrix — who sends to whom (from from:/to: frontmatter)
• Friction matrix — who challenges whom (from friction markers in body)
• Orchestrator friction — frictions from session summaries (## Orchestrator friction)
• reportPattern() — convergence detection across rejected frictions

These are observational — no pass/fail, just data.

Conventions

Instance conventions. Extend as the project evolves.

Artifact types

Declare which artifact types this instance uses. The audit checks only declared types.

<!-- Add rows for additional types used by this instance, e.g.:

-->

Structure

Maintain as you go. When a new directory appears in shared/ (notes/, review/, etc.), add it here so personas know where to look and where to deposit.

instance/
├── sofia.md
├── shared/
│   ├── conventions.md
│   └── orga/
│       ├── personas/
│       └── contextes/
├── {space}/
│   ├── CLAUDE.md
│   └── sessions/
└── ...

Repo ownership (optional)

<!-- Uncomment and fill if your instance spans external repos.

-->

Sessions

Session summary

At each closure, the persona creates a file in {space}/sessions/:

{YYYY-MM-DD}-{HHmm}-{persona}.md

HHmm is the closure time (not the boot time).

Session frontmatter

---
persona: persona-name
date: YYYY-MM-DD
session: "HHmm"
---

Protocol sections (MUST)

No prose — short lists. 30 lines max.

Observational sections

Commits

{persona}: {short summary} ({date})

One commit per session.

Artifacts

Every artifact deposited in shared/ carries a YAML frontmatter.

---
from: emitting-persona
to: recipient-persona
nature: signal           # signal | question | request | response
status: new              # new | read | done
date: YYYY-MM-DD
ref: source-artifact     # SHOULD when nature = response (filename without extension)
---

Lifecycle

Resolution

When an artifact is processed, each point SHOULD carry a resolution tag in the document body:

→ ratified | → contested | → revised | → rejected

Friction

Each line carries: marker + description + initiative + resolution.

- [marker] description — [initiative] → resolution

Markers

5 epistemic positions. Closed set — do not add new ones.

Bracketed keywords are authoritative for the audit.

Initiative

[persona] or [PO] — who initiated the friction topic.

Resolution

One tag per friction point.

Cross-session mutability

A resolution may evolve in a later session. The friction SHOULD carry a ref: field pointing to the original friction:

- ✓ [sound] description — [persona] → ratified (ref: 2026-04-10-1430-persona/3)

Quick reading

• Only ✓ → absent friction — alert signal
• Mix ✓/~/⚡ → healthy friction
• Presence of ◐ or ✗ → tension to address
• No resolution → unresolved frictions, to address or report in Open

Contribution (epistemic flow)

Section ## Flow — optional.

- {direction}:{type} — description

Optional counting at end of section.

Roadmaps

Roadmaps live in shared/ and follow the naming convention roadmap-{product}.md.

Structure

Each roadmap SHOULD have:

• A # Roadmap {name} header
• An owner declaration in the blockquote: > Owner : @persona
• Version sections (### vX.Y.Z) with metadata comments: <!-- produit: X | cible: YYYY-MM | statut: todo -->

Items

Each item is a markdown list entry (- [status] description @owner).

• Status: [done], [running], [todo], [blocked], [ready]
• Owner: @persona — who is responsible
• Cross-instance: ↔ marker for dependencies on other instances

Cross-instance exchanges

When the orchestrator routes an artifact between two instances, the artifact MUST be deposited in shared/ of the recipient's instance — not the emitter's.

The emitting persona does not need to know the recipient's instance. The orchestrator crosses instance boundaries — personas remain isolated.

See protocol/exchange.md §Cross-instance exchanges.