Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,30 @@ This project uses [Semantic Versioning](https://semver.org/).

---

## [0.3.0] — 2026-07-18

### Added

- **RFC-0001** — Added Property 4 provenance requirements for continuity-bearing memory entries, including standard admission path definition and audit-log dependency.
- **RFC-0001 §5.6** — Added `memory_entry_admitted` and `principal_authorized_write` audit event vocabulary for falsifiable source attestations.
- **RFC-0001 §5.6** — Required evidence fields at the provenance-chain anchors: `principal_authorized_write` and `ward_updated` events MUST carry `principal_authorization` (and `ward_updated` additionally `ward_version`/`ward_hash`); attestations resolving to events lacking them are unverified, and unresolvable attestation referents MUST be rejected.
- **RFC-0001 §1.1** — Defined "Committed Ward state" and "Continuity-bearing" (with fail-closed classification default); scoped the Ward-manifest equivalent-form allowance to authority-layer runtime storage.
- **RFC-0001 §3.4** — Attestation establishes provenance, not authorization: loop-originated entries additionally require explicit human authorization, recorded on the admission event (§5.6); ambiguous origin is treated as loop-originated.
- **RFC-0001 §4.1** — Genesis bootstrap note: closure is satisfiable from the first principal-authorized Ward write.
- **RFC-0001 §5.4 / §9** — Gate 4 re-verifies Ward-manifest closure before promotion; documented runtime closure verification as an open testing gap.
- **tests/conformance/negative/10-protected-missing-ward/** — Added negative fixture for a Ward manifest omitted from `[protected].files`.

### Changed

- **RFC-0001** — Bumped draft version to v0.3.0 for new backward-compatible normative requirements.
- **RFC-0001 §4.1 / §5.4** — Strengthened Ward-manifest closure prose and Gate 1 fail-closed behavior.
- **RFC-0001 §3.4 / §5.6** — Replaced the undefined "claiming Property 4 provenance" condition with "an implementation that provides a standard admission path (§1.1)".
- **RFC-0001 §6.3** — Redefined semver categories: Major now covers *incompatible* changes to the five properties or existing conformance requirements; Minor covers backward-compatible normative additions (previously any change to MUST-level requirements read as Major).
- **README.md, rfcs/README.md, SPEC.md, docs/faq.md, validators/validate.js** — Updated current-version references to v0.3.0.
- **docs/ward-deep-dive.md** — Updated version references to v0.3.0 and reframed the open-questions horizon.

---

## [0.2.0] — 2026-06-19

### Added
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> **The Familiar Contract is an open specification for what an agent is allowed to be — not just what it can do, but what it cannot change about itself.**

[![specification: v0.2.0](https://img.shields.io/badge/specification-v0.2.0-8b5cf6)](rfcs/RFC-0001-familiar-contract.md)
[![specification: v0.3.0](https://img.shields.io/badge/specification-v0.3.0-8b5cf6)](rfcs/RFC-0001-familiar-contract.md)
[![RFC-0001: Draft](https://img.shields.io/badge/RFC--0001-Draft-blue)](rfcs/RFC-0001-familiar-contract.md)
[![license: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/OpenCoven/familiar-contract)
Expand Down
2 changes: 1 addition & 1 deletion SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> **Status:** Superseded · **License:** MIT · **Version:** 0.1.0
>
> ⚠️ **This document is preserved for reproducibility.** The current normative specification is [RFC-0001 v0.2.0](rfcs/RFC-0001-familiar-contract.md), which uses RFC 2119 keywords (MUST/SHOULD/MAY), references the conformance suite at [`tests/conformance/`](tests/conformance/), and hardens the authority-layer separation requirement.
> ⚠️ **This document is preserved for reproducibility.** The current normative specification is [RFC-0001 v0.3.0](rfcs/RFC-0001-familiar-contract.md), which uses RFC 2119 keywords (MUST/SHOULD/MAY), references the conformance suite at [`tests/conformance/`](tests/conformance/), and hardens the authority-layer separation requirement.
>
> If you are looking for the current spec, go to [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md). This file remains for historical and citation purposes.

Expand Down
10 changes: 5 additions & 5 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The core problem it addresses is this: AI agents have gotten very capable, but t

The specification has two major parts. First, a five-property identity contract: a compliant "familiar" must have a stable named identity, a declared purpose, enforced authority limits, persistent memory, and an explicit binding to a specific person. Second, an enforcement model built around a component called the Ward — a TOML policy document plus a runtime enforcement daemon that checks proposed changes against the protected surface before they are applied. The key word is "enforced": the Ward is not asking the agent to have good values about self-modification. It is an external check that runs regardless of what the agent thinks about it.

The Familiar Contract is a normative specification, which means it defines what must be true about a compliant system, tested against an executable conformance suite, not just described. The RFC (RFC-0001, v0.2.0) carries formal RFC 2119 keywords (MUST, MUST NOT, SHOULD) and the `tests/conformance/` directory is the spec made executable. A system that passes every positive case and fails every negative case is, by definition, conformant.
The Familiar Contract is a normative specification, which means it defines what must be true about a compliant system, tested against an executable conformance suite, not just described. The RFC (RFC-0001, v0.3.0) carries formal RFC 2119 keywords (MUST, MUST NOT, SHOULD) and the `tests/conformance/` directory is the spec made executable. A system that passes every positive case and fails every negative case is, by definition, conformant.

---

Expand Down Expand Up @@ -245,9 +245,9 @@ For structural conformance, the steps are:
1. Create a familiar directory with all required files: `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `ward.toml`.
2. Ensure `SOUL.md` includes the required sections: at minimum a name, pronouns, purpose, character description, and a `## What I Am Not` section.
3. Ensure `ward.toml` conforms to `schemas/ward.schema.json`. The Ward must include `[meta]` (with `version`, `familiar`, `person`), `[protected]` (with `files` listing the four required protected files and an `invariants` array covering name and person), `[editable]`, and `[approval_tiers]` (with at minimum `auto` and `human_review` defined).
4. Run `bash tests/conformance/run-conformance.sh` from the repo root. All five positive cases must pass. All nine negative cases must fail (demonstrating that the validator catches each documented violation).
4. Run `bash tests/conformance/run-conformance.sh` from the repo root. All five positive cases must pass. All ten negative cases must fail (demonstrating that the validator catches each documented violation).

If the conformance run returns `0` for positive cases and the validator correctly rejects all negative cases, the familiar is structurally conformant with v0.2.0. Claim conformance by declaring the version in your documentation and keeping a passing conformance run reproducible from your repo.
If the conformance run returns `0` for positive cases and the validator correctly rejects all negative cases, the familiar is structurally conformant with v0.3.0. Claim conformance by declaring the version in your documentation and keeping a passing conformance run reproducible from your repo.

Full conformance — including runtime conformance — requires a running Ward daemon with proper authority-layer separation, an append-only audit log, and verified identity-probe consistency. These are not testable from a directory alone and are acknowledged as open testing gaps in RFC §9. A claim of full conformance should specify which layers have been verified.

Expand Down Expand Up @@ -276,7 +276,7 @@ The RFC also does not address security of the authority layer itself. If the War
What you need is: a familiar directory with the required files (`SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `ward.toml`); a `ward.toml` that conforms to the published schema; and an enforcement mechanism — a Ward authority daemon — that is structurally separate from the familiar's own logic. The reference implementation uses a Rust authority daemon (the `coven` layer), but the RFC is explicit that "other implementations may choose different mechanisms; what is normative is the separation, not the implementation."
The structural conformance suite (`tests/conformance/`) runs against any familiar directory and has no Coven dependencies. The validator (`validators/validate.js`) requires only Node.js. The schemas (`schemas/`) are standard JSON Schema and can be validated with any conforming schema validator.

The parts of the spec that are Coven-specific — Doll proposals, Cave Board integration, multi-familiar routing — are referenced as context, not as requirements. A standalone familiar implementing a Ward daemon without any Coven infrastructure can be fully conformant with RFC-0001 v0.2.0.
The parts of the spec that are Coven-specific — Doll proposals, Cave Board integration, multi-familiar routing — are referenced as context, not as requirements. A standalone familiar implementing a Ward daemon without any Coven infrastructure can be fully conformant with RFC-0001 v0.3.0.

---

Expand All @@ -290,6 +290,6 @@ If you want to understand how the Familiar Contract relates to other agent speci

If you want to build a conformant familiar, start with `ward.toml` (conforming to `schemas/ward.schema.json`), create the required files, run `bash tests/conformance/run-conformance.sh`, and iterate until the suite passes. The negative test cases tell you exactly what the validator checks for and why.

If you want to cite the specification in a paper, the canonical reference is RFC-0001 v0.2.0, available at `rfcs/RFC-0001-familiar-contract.md`. The accompanying paper (Alexander, 2026, forthcoming on arXiv) provides the academic framing including the principal-agent formulation, comparison with Self-Harness and SkillOpt, and formal definitions. The Ward spec (v0.2, `research/synthesis/ward-spec-v0.2-draft.md`) provides the implementation-level reference for Ward daemon builders.
If you want to cite the specification in a paper, the canonical reference is RFC-0001 v0.3.0, available at `rfcs/RFC-0001-familiar-contract.md`. The accompanying paper (Alexander, 2026, forthcoming on arXiv) provides the academic framing including the principal-agent formulation, comparison with Self-Harness and SkillOpt, and formal definitions. The Ward deep dive (`docs/ward-deep-dive.md`) provides the implementation-level reference for Ward daemon builders.

If you have questions that are not answered here, open an issue in the repository.
8 changes: 4 additions & 4 deletions docs/ward-deep-dive.md
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ What is normative is not that the Ward never changes, but that changes to the Wa

## 10. Open questions

RFC-0001 v0.2.0 is a solid foundation. It is not the last word. The following are genuine open questions that v0.3 and beyond will need to address.
RFC-0001 v0.3.0 is a solid foundation. It is not the last word. v0.3.0 closed two earlier gaps — Ward-manifest closure (`ward.toml` must be a member of its own `[protected].files`) and falsifiable memory-entry provenance (§3.4, §5.6). The following are genuine open questions that future revisions will need to address.

### Authority layer conformance testing

Expand All @@ -333,11 +333,11 @@ Similarly: verifying that Gate 4 cannot be skipped requires an integration test

### Proposal format specification

The RFC specifies what a proposal must contain (origin, targets, diff, metadata) but not the serialization format. Different self-improvement loop implementations will produce proposals in different formats. A v0.3 proposal format spec — or at least a normative schema — would improve interoperability between loops and Ward daemon implementations.
The RFC specifies what a proposal must contain (origin, targets, diff, metadata) but not the serialization format. Different self-improvement loop implementations will produce proposals in different formats. A future proposal format spec — or at least a normative schema — would improve interoperability between loops and Ward daemon implementations.

### Identity probe standardization

The RFC requires identity probes but specifies only a few example questions. The exact probe set matters: a minimal probe set might miss identity drift on dimensions that matter to a particular familiar. A v0.3 contribution could be a standardized identity probe library — a set of probe questions organized by invariant type, with recommended evaluation rubrics.
The RFC requires identity probes but specifies only a few example questions. The exact probe set matters: a minimal probe set might miss identity drift on dimensions that matter to a particular familiar. A future contribution could be a standardized identity probe library — a set of probe questions organized by invariant type, with recommended evaluation rubrics.

### Multi-familiar proposal interactions

Expand All @@ -359,4 +359,4 @@ Regression suites are currently familiar-specific and opaque to the conformance

*The Ward is the structural answer to a structural problem. Self-improvement loops are real, they are in production, and they can drift an agent's identity over time without a principled enforcement boundary. The Ward provides that boundary — not through agent cooperation, but through authority-layer enforcement that holds regardless of what the agent thinks about it. That distinction is what the Familiar Contract is built on.*

*RFC-0001 v0.2.0 — 2026-06-19. `rfcs/RFC-0001-familiar-contract.md`.*
*RFC-0001 v0.3.0 — 2026-07-18. `rfcs/RFC-0001-familiar-contract.md`.*
8 changes: 4 additions & 4 deletions rfcs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The RFC is the spec. The schemas are the machine-readable form. The conformance

| Number | Title | Version | Status |
|---|---|---|---|
| [RFC-0001](RFC-0001-familiar-contract.md) | The Familiar Contract | v0.2.0 | Draft |
| [RFC-0001](RFC-0001-familiar-contract.md) | The Familiar Contract | v0.3.0 | Draft |

## Process

Expand All @@ -43,14 +43,14 @@ Proposed → Draft → Review → Accepted → (Superseded)
## How to cite an RFC

```
Familiar Contract RFC-0001 v0.2.0, "The Familiar Contract."
Familiar Contract RFC-0001 v0.3.0, "The Familiar Contract."
OpenCoven, 2026. https://github.com/OpenCoven/familiar-contract/blob/main/rfcs/RFC-0001-familiar-contract.md
```

For academic citation, prefer the tagged release:
For academic citation, prefer the tagged release (the `v0.3.0` tag is cut when the corresponding RFC revision merges; until then, cite the latest existing tag):

```
https://github.com/OpenCoven/familiar-contract/releases/tag/v0.2.0
https://github.com/OpenCoven/familiar-contract/releases/tag/v0.3.0
```

## License
Expand Down
Loading