Skip to content
Merged
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
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,20 @@ This project uses [Semantic Versioning](https://semver.org/).

---

## [0.4.1] — 2026-07-21

Draft patch (§6.3): clarifications only; no conformance requirements change.

### Changed

- **RFC-0001 §1.1** — Completed the *standard admission path* definition with the §3.4 loop-origin authorization step (clarification; no new requirement).
- **RFC-0001 §5.6** — Annotated the evidence-field list with per-event-type MUST pointers, including `principal_authorization` on loop-originated `memory_entry_admitted` events (cross-reference; no new requirement).
- **tests/conformance/negative/09-missing-memory/CASE.md** — Corrected the false claim that the validator reports missing `MEMORY.md` "as a warning only" (it is a violation since v0.2.0) and dropped the stale v0.2 anchor.
- **tests/conformance/positive/05-tier-rich-ward/CASE.md** — Reanchored the tier-name citation from "the v0.2 RFC frame" to RFC-0001 §5.3.
- **README.md, PRIMER.md, SPEC.md, rfcs/README.md, docs/faq.md, tests/conformance/README.md, validators/README.md, validators/validate.js, package.json** — Updated current-version references to v0.4.1.

---

## [0.4.0] — 2026-07-19

### Added
Expand Down
2 changes: 1 addition & 1 deletion PRIMER.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ You do not need to use OpenCoven's infrastructure to implement familiar-contract

## Where to go next

- [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative specification (v0.4.0)
- [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative specification (v0.4.1)
- [`examples/minimal/`](examples/minimal/) — the minimal structurally conformant familiar directory (Lumen)
- [`examples/sage/`](examples/sage/) — a richer structurally conformant familiar directory (Sage)
- `node validators/validate.js ./your-directory` — validate your claimant directory
Expand Down
12 changes: 6 additions & 6 deletions 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.4.0](https://img.shields.io/badge/specification-v0.4.0-8b5cf6)](rfcs/RFC-0001-familiar-contract.md)
[![specification: v0.4.1](https://img.shields.io/badge/specification-v0.4.1-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 Expand Up @@ -40,11 +40,11 @@ These are not soft design preferences. Each one has architectural implications,
## How to Use This Spec

**If you're building a familiar:**
1. Read [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative spec (v0.4.0)
1. Read [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative spec (v0.4.1)
2. Copy an example from [`examples/`](examples/) — `minimal/` for the floor, `sage/` for a richer structurally conformant familiar directory
3. Create `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, and `ward.toml` for your familiar
4. Run `npm install` to install the reference validator's TOML parser and JSON Schema validator.
5. For a v0.4.0 structural-conformance claim, run both `node validators/validate.js ./your-directory` and `npm test`
5. For a v0.4.1 structural-conformance claim, run both `node validators/validate.js ./your-directory` and `npm test`

**If you're evaluating a familiar:**
- Five properties. All five. Fewer than five is an agent, not a familiar.
Expand All @@ -62,10 +62,10 @@ These are not soft design preferences. Each one has architectural implications,
# Install the reference validator dependencies
npm install

# Validate the claimant directory for your v0.4.0 claim
# Validate the claimant directory for your v0.4.1 claim
node validators/validate.js ./your-directory

# Verify the bundled reference validator + fixtures for the same v0.4.0 claim
# Verify the bundled reference validator + fixtures for the same v0.4.1 claim
npm test
```

Expand All @@ -88,7 +88,7 @@ See [`validators/README.md`](validators/README.md) for full CLI docs.
## Repository Contents

```
rfcs/RFC-0001-familiar-contract.md ← The Familiar Contract (normative, v0.4.0)
rfcs/RFC-0001-familiar-contract.md ← The Familiar Contract (normative, v0.4.1)
README.md ← This file
PRIMER.md ← Builder's guide (for new readers)
CHANGELOG.md ← Version history
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:** Historical / superseded · **License:** MIT · **Version:** 0.1.0
>
> ⚠️ **This document is preserved for reproducibility.** The current normative specification is [RFC-0001 v0.4.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.4.1](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
6 changes: 3 additions & 3 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 conformant system, tested against both a claimant-directory validator run and an executable conformance suite, not just described. The RFC (RFC-0001, v0.4.0) carries formal RFC 2119 keywords (MUST, MUST NOT, SHOULD) and the `tests/conformance/` directory is the fixture suite that verifies the reference validator. A familiar directory is structurally conformant only when `node validators/validate.js ./your-directory` succeeds and `bash tests/conformance/run-conformance.sh` passes in the repository. Full conformance also requires runtime Ward enforcement as described in RFC §6.2.
The Familiar Contract is a normative specification, which means it defines what must be true about a conformant system, tested against both a claimant-directory validator run and an executable conformance suite, not just described. The RFC (RFC-0001, v0.4.1) carries formal RFC 2119 keywords (MUST, MUST NOT, SHOULD) and the `tests/conformance/` directory is the fixture suite that verifies the reference validator. A familiar directory is structurally conformant only when `node validators/validate.js ./your-directory` succeeds and `bash tests/conformance/run-conformance.sh` passes in the repository. Full conformance also requires runtime Ward enforcement as described in RFC §6.2.

---

Expand Down Expand Up @@ -278,7 +278,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/`) has no Coven dependencies, but it does not by itself validate an arbitrary external directory. It verifies that the bundled reference validator accepts the positive fixtures and rejects the negative fixtures. Your own familiar directory still needs its own `node validators/validate.js ./your-directory` run. The reference validator requires Node.js plus `npm install`; its dependencies are a standards-compliant TOML parser and JSON Schema validator. 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.4.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.4.1.

---

Expand All @@ -292,6 +292,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 `node validators/validate.js ./your-directory`, then run `bash tests/conformance/run-conformance.sh`, and iterate until both pass. 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.4.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 public companion authority-boundary design for Ward daemon builders is [OpenCoven/coven-threads `specs/PHASE-0-DESIGN.md`](https://github.com/OpenCoven/coven-threads/blob/main/specs/PHASE-0-DESIGN.md), but RFC-0001 §5 remains the normative Familiar Contract requirement.
If you want to cite the specification in a paper, the canonical reference is RFC-0001 v0.4.1, 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 public companion authority-boundary design for Ward daemon builders is [OpenCoven/coven-threads `specs/PHASE-0-DESIGN.md`](https://github.com/OpenCoven/coven-threads/blob/main/specs/PHASE-0-DESIGN.md), but RFC-0001 §5 remains the normative Familiar Contract requirement.

If you have questions that are not answered here, open an issue in the repository.
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "familiar-contract",
"version": "0.4.0",
"version": "0.4.1",
"private": true,
"type": "commonjs",
"scripts": {
Expand Down
6 changes: 3 additions & 3 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 | Notes |
|---|---|---|---|---|
| [RFC-0001](RFC-0001-familiar-contract.md) | The Familiar Contract | v0.4.0 | Draft | Canonical current draft |
| [RFC-0001](RFC-0001-familiar-contract.md) | The Familiar Contract | v0.4.1 | Draft | Canonical current draft |

## Historical snapshots

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

```
Familiar Contract RFC-0001 v0.4.0, "The Familiar Contract."
Familiar Contract RFC-0001 v0.4.1, "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 (the version 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.4.0
https://github.com/OpenCoven/familiar-contract/releases/tag/v0.4.1
```

## License
Expand Down
Loading