diff --git a/CHANGELOG.md b/CHANGELOG.md index f360640..3cd4819 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,24 @@ This project uses [Semantic Versioning](https://semver.org/). --- +## [0.5.0] — 2026-07-24 + +Draft minor, classified under the **v0.4.1** §6.3 rule per the incoming §6.3.1 freeze: one additive normative change, shipped alone. No directory-level conformance requirements change. + +### Added + +- **RFC-0001 §6.3.1** — Amendment freeze for the versioning rule: a release changing §6.3 **MUST NOT** contain any other normative change (current-version anchor substitutions inside otherwise-unchanged normative sentences excepted), **MUST** be classified under the §6.3 rule ratified in the most recent prior release (never the rule it introduces), a changed rule governs only later releases, and ambiguous classification under the prior rule **MUST** take the larger bump. Closes the self-ratification pattern (v0.4.0 review finding A-1; first flagged as A-7 in the v0.3.0 review). +- **RFC-0001 §9** — Testing-gap bullet for §6.3.1 (release-process property; verified in release history and review, not by the file-level suite). +- **rfcs/RFC-0001-v0.4.md** — Historical snapshot of the final v0.4.x text (exact copy of tag `v0.4.1`). + +### Changed + +- **Migration impact:** none. Directories structurally conformant with v0.4.1 remain structurally conformant with v0.5.0; the new MUSTs bind the RFC's own release process, not implementations. +- **Security rationale:** §6.3 is the specification's own authority boundary; a release blessed by the versioning rule it introduces is self-ratifying — the specification-layer analogue of the Ward-mutation loophole Gate 4 closes. The freeze makes the amendment rule a protected surface of the spec itself. +- **README.md, PRIMER.md, SPEC.md, rfcs/README.md, docs/faq.md, tests/conformance/README.md, validators/README.md, validators/validate.js, schemas/ward.schema.json (description string), package.json** — Updated current-version references to v0.5.0. + +--- + ## [0.4.1] — 2026-07-21 Draft patch (§6.3): clarifications only; no conformance requirements change. diff --git a/PRIMER.md b/PRIMER.md index a49fcea..175c849 100644 --- a/PRIMER.md +++ b/PRIMER.md @@ -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.1) +- [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative specification (v0.5.0) - [`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 diff --git a/README.md b/README.md index 3aadf27..c110b5e 100644 --- a/README.md +++ b/README.md @@ -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.1](https://img.shields.io/badge/specification-v0.4.1-8b5cf6)](rfcs/RFC-0001-familiar-contract.md) +[![specification: v0.5.0](https://img.shields.io/badge/specification-v0.5.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) @@ -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.1) +1. Read [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative spec (v0.5.0) 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.1 structural-conformance claim, run both `node validators/validate.js ./your-directory` and `npm test` +5. For a v0.5.0 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. @@ -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.1 claim +# Validate the claimant directory for your v0.5.0 claim node validators/validate.js ./your-directory -# Verify the bundled reference validator + fixtures for the same v0.4.1 claim +# Verify the bundled reference validator + fixtures for the same v0.5.0 claim npm test ``` @@ -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.1) +rfcs/RFC-0001-familiar-contract.md ← The Familiar Contract (normative, v0.5.0) README.md ← This file PRIMER.md ← Builder's guide (for new readers) CHANGELOG.md ← Version history diff --git a/SPEC.md b/SPEC.md index dd88a9d..1dcb742 100644 --- a/SPEC.md +++ b/SPEC.md @@ -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.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. +> ⚠️ **This document is preserved for reproducibility.** The current normative specification is [RFC-0001 v0.5.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. diff --git a/docs/faq.md b/docs/faq.md index 2c0a98f..1d55c8c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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.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. +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.5.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. --- @@ -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.1. +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.5.0. --- @@ -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.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 want to cite the specification in a paper, the canonical reference is RFC-0001 v0.5.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 have questions that are not answered here, open an issue in the repository. diff --git a/package-lock.json b/package-lock.json index 47402ab..5abfc1e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "familiar-contract", - "version": "0.4.1", + "version": "0.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "familiar-contract", - "version": "0.4.1", + "version": "0.5.0", "dependencies": { "@iarna/toml": "2.2.5", "ajv": "8.20.0" diff --git a/package.json b/package.json index f4bf533..e6d69e3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "familiar-contract", - "version": "0.4.1", + "version": "0.5.0", "private": true, "type": "commonjs", "scripts": { diff --git a/rfcs/README.md b/rfcs/README.md index 94b5442..a4efa4b 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -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.1 | Draft | Canonical current draft | +| [RFC-0001](RFC-0001-familiar-contract.md) | The Familiar Contract | v0.5.0 | Draft | Canonical current draft | ## Historical snapshots @@ -28,6 +28,7 @@ do not edit them in place. | Snapshot | Version | Status | Source | |---|---|---|---| +| [RFC-0001-v0.4](RFC-0001-v0.4.md) | v0.4.1 | Historical snapshot | tag `v0.4.1` (main `8a2dfd2`) | | [RFC-0001-v0.3](RFC-0001-v0.3.md) | v0.3.0 | Historical snapshot | tag `v0.3.0` (main `710036e`) | | [RFC-0001-v0.2](RFC-0001-v0.2.md) | v0.2.0 | Historical snapshot | `808ae167d8bfea7f2162f84b6f4c9269d319a9b1` | @@ -49,21 +50,21 @@ Proposed → Draft → Review → Accepted → (Superseded) **Numbering:** RFCs are numbered in the order they enter `Draft` status. Numbers are not reused. -**Draft versioning:** While an RFC remains `Draft`, it **MUST** stay below `1.0.0`. Draft patch versions (`0.y.z`, `z > 0`) are for clarifications and fixes that do not change conformance requirements. Draft minor versions (`0.y.0`) **MAY** introduce backward-incompatible or additive conformance changes, but each such release **MUST** document migration impact and security rationale, and consumers **MUST** pin the exact version they implement. Once an RFC reaches `1.0.0` or higher, standard SemVer applies: major for incompatible changes, minor for backward-compatible additions, patch for clarifications and fixes. +**Draft versioning:** While an RFC remains `Draft`, it **MUST** stay below `1.0.0`. Draft patch versions (`0.y.z`, `z > 0`) are for clarifications and fixes that do not change conformance requirements. Draft minor versions (`0.y.0`) **MAY** introduce backward-incompatible or additive conformance changes, but each such release **MUST** document migration impact and security rationale, and consumers **MUST** pin the exact version they implement. A release that changes the versioning rule itself (RFC-0001 §6.3) **MUST** ship with no other normative change and **MUST** be classified under the previously ratified rule, never the rule it introduces (RFC-0001 §6.3.1). Once an RFC reaches `1.0.0` or higher, standard SemVer applies: major for incompatible changes, minor for backward-compatible additions, patch for clarifications and fixes. **Conformance:** Every normative requirement (a sentence containing MUST or SHOULD) in an Accepted RFC SHOULD have a corresponding test in `tests/conformance/`. RFCs that lack conformance coverage may still be Accepted, but the gap is documented in the RFC itself under an "Open testing gaps" section. ## How to cite an RFC ``` -Familiar Contract RFC-0001 v0.4.1, "The Familiar Contract." +Familiar Contract RFC-0001 v0.5.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 (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.1 +https://github.com/OpenCoven/familiar-contract/releases/tag/v0.5.0 ``` ## License diff --git a/rfcs/RFC-0001-familiar-contract.md b/rfcs/RFC-0001-familiar-contract.md index 6ba42e1..0f57925 100644 --- a/rfcs/RFC-0001-familiar-contract.md +++ b/rfcs/RFC-0001-familiar-contract.md @@ -4,10 +4,10 @@ |---|---| | **Number** | RFC-0001 | | **Title** | The Familiar Contract | -| **Version** | 0.4.1 | +| **Version** | 0.5.0 | | **Status** | Draft | | **Authors** | Valentina Alexander, Sage | -| **Date** | 2026-07-21 | +| **Date** | 2026-07-24 | | **Supersedes** | SPEC.md v0.1.0 (in-tree predecessor; non-RFC form) | | **License** | MIT | | **Conformance** | `tests/conformance/` | @@ -20,7 +20,7 @@ This document defines the Familiar Contract: a normative specification for a cla The Familiar Contract addresses an architectural gap in current agent systems: the absence of a principled answer to the question *what is this agent not allowed to change about itself?* As recursive self-improvement loops (Self-Harness, Skill-Opt, sleep-time compute) become production-deployable, the absence of a protected surface is a design flaw, not an oversight. -This RFC is the formal, testable, citable specification. A familiar directory is structurally conformant with v0.4.1 only if `node validators/validate.js ` succeeds and `bash tests/conformance/run-conformance.sh` passes in this repository. +This RFC is the formal, testable, citable specification. A familiar directory is structurally conformant with v0.5.0 only if `node validators/validate.js ` succeeds and `bash tests/conformance/run-conformance.sh` passes in this repository. --- @@ -320,14 +320,14 @@ A `memory_entry_admitted` event **MUST** include an `entry_hash` for the admitte ### 6.1 Conformance test suite -The directory `tests/conformance/` contains the executable reference conformance suite for this RFC. A claimant directory is **structurally conformant with v0.4.1** if and only if **BOTH** of the following are true: +The directory `tests/conformance/` contains the executable reference conformance suite for this RFC. A claimant directory is **structurally conformant with v0.5.0** if and only if **BOTH** of the following are true: - `node validators/validate.js ` succeeds for the claimant directory making the conformance claim. - `bash tests/conformance/run-conformance.sh` passes in this repository, demonstrating that the reference validator accepts every bundled positive fixture in `tests/conformance/positive/` and rejects every bundled negative fixture in `tests/conformance/negative/`. The claimant directory does **NOT** itself "pass the fixture suite"; the reference suite verifies the validator's behavior against bundled fixtures, while the claimant-directory run verifies the directory making the claim. Together they establish the structural claim only. They do **NOT** by themselves prove authority-layer separation, Gate 4 unbypassability, audit-log behavior, identity-probe consistency, or any other runtime requirement for full conformance. -A claim of v0.4.1 structural conformance **MUST** be backed by reproducible passing runs of both commands. +A claim of v0.5.0 structural conformance **MUST** be backed by reproducible passing runs of both commands. ### 6.2 Validator @@ -343,7 +343,18 @@ This RFC uses [Semantic Versioning](https://semver.org/) with an explicit draft - **Stable minor** (`x.y.0`, where `x >= 1` and `y > 0`): Backward-compatible normative additions and compatible schema evolution. - **Stable major** (`x.0.0`, where `x >= 1`): Backward-incompatible changes to existing conformance requirements or to the five properties. Requires a new RFC that supersedes this one. -A familiar claiming compliance with `v0.4.1` **MUST** satisfy the normative core as defined in this version. While this RFC remains `Draft`, clarifications and fixes that do not change conformance requirements **MUST** use a draft patch version bump; documented additive or breaking conformance changes **MUST** use a draft minor version bump. Once this RFC reaches `1.0.0` or higher, incompatible changes **MUST** use a major version bump; compatible additions **MUST** use a minor version bump; clarifications and fixes **MUST** use a patch version bump. +A familiar claiming compliance with `v0.5.0` **MUST** satisfy the normative core as defined in this version. While this RFC remains `Draft`, clarifications and fixes that do not change conformance requirements **MUST** use a draft patch version bump; documented additive or breaking conformance changes **MUST** use a draft minor version bump. Once this RFC reaches `1.0.0` or higher, incompatible changes **MUST** use a major version bump; compatible additions **MUST** use a minor version bump; clarifications and fixes **MUST** use a patch version bump. + +#### 6.3.1 Amendment rule for this section + +The rules in §6.3 are this specification's own authority boundary: they classify how every other rule may change. A release that redefines the versioning rule and is classified under the redefinition it introduces is self-ratifying — the specification-layer analogue of the self-modification failure mode that Gate 4 (§5.4) exists to prevent at the Ward layer, where a mutation **MUST** be validated against the currently committed Ward, never against the state the mutation itself proposes. This occurred in v0.4.0 (ratified retroactively and explicitly in its merge record) after the same pattern was flagged in the v0.3.0 review. To close it: + +- A release that changes §6.3 (including this subsection) **MUST NOT** contain any other normative change. Substituting the current-version anchor inside an otherwise-unchanged normative sentence (for example, the version named by the §6.1 conformance-claim sentences) is inherent to every release and is not an "other normative change" for the purposes of this rule. +- Such a release **MUST** be classified (draft patch, draft minor, or the post-`1.0.0` equivalents) according to the §6.3 rule ratified in the most recent prior release — never according to the rule it introduces. +- A changed §6.3 rule governs only releases after the release that introduces it. +- If classification under the previously ratified rule is ambiguous, the release **MUST** take the larger version bump. + +This subsection was introduced in v0.5.0 and is itself classified under the v0.4.1 §6.3 rule: it is an additive normative change, therefore a draft minor bump, and it ships with no other normative change. --- @@ -420,6 +431,7 @@ The following requirements in this RFC are **NOT yet covered** by the conformanc - **Memory-entry provenance (§3.4, §5.6).** The audit log now defines recordable `memory_entry_admitted` evidence, but verifying source-attestation chains still requires access to prior committed Ward states and principal-authorized write events. This is a runtime/audit-log integration concern, not a directory-level structural check. - **Runtime closure verification (§4.1, §5.4).** Gate-1 and Gate-4 verification that the currently committed Ward manifest is a member of its own `[protected].files` is runtime behavior. The conformance suite covers only the structural side (fixture `negative/10-protected-missing-ward`); verifying the running authority layer refuses intake and promotion under a non-closed Ward requires an integration test against a Ward daemon. - **Approval-path compilation and veto-window enforcement (§5.3.1).** The structural suite verifies that tier declarations compile deterministically and fail closed on the documented error classes. Binding each `SurfaceRegionId` to a deterministic extractor, delayed apply with evidence replay and Gate-4 re-run at veto-window expiry, and fail-closed Ward *loading* in the running authority layer are runtime behaviors requiring integration tests against a Ward daemon. +- **Versioning-rule amendment freeze (§6.3.1).** The requirements that a §6.3 change ship with no other normative change and be classified under the previously ratified rule are release-process properties. They are visible in the repository's release history and enforced by review at release time, not testable from a claimant directory or by the file-level conformance suite. These gaps are intentional. The file-level conformance suite verifies the **structural** claim. The system-level claim requires runtime testing against a Ward daemon implementation. Both are part of the full conformance picture. @@ -433,7 +445,7 @@ These gaps are intentional. The file-level conformance suite verifies the **stru - **`schemas/soul.schema.json`** — Required structural fields of `SOUL.md`. - **`schemas/identity.schema.json`** — Required structural fields of `IDENTITY.md`. - **`schemas/ward.schema.json`** — Required structural fields of `ward.toml`. -- **`tests/conformance/`** — Executable conformance suite for v0.4.1. +- **`tests/conformance/`** — Executable conformance suite for v0.5.0. ### 10.2 Informative @@ -453,6 +465,16 @@ These gaps are intentional. The file-level conformance suite verifies the **stru ## 11. Changelog +### v0.5.0 (2026-07-24) + +Draft minor, classified under the **v0.4.1** §6.3 rule per the incoming §6.3.1 freeze: one additive normative change (amendment-process MUSTs), shipped with no other normative change. No directory-level conformance requirement changes. + +- Added §6.3.1: a release that changes §6.3 **MUST NOT** contain any other normative change (current-version anchor substitutions inside otherwise-unchanged normative sentences excepted, as inherent to every release); **MUST** be classified under the §6.3 rule ratified in the most recent prior release, never the rule it introduces; a changed rule governs only later releases; ambiguous classification under the prior rule **MUST** take the larger bump. Closes the self-ratification pattern from the v0.4.0 review (finding A-1; first flagged as A-7 in the v0.3.0 review) that was retroactively ratified in the v0.4.0 merge record. +- **Migration impact:** none. No familiar-directory conformance requirements change; directories structurally conformant with v0.4.1 are structurally conformant with v0.5.0. Consumers pinning v0.4.1 are unaffected. The new MUSTs bind this RFC's own release process, not implementations. +- **Security rationale:** §6.3 is the specification's own authority boundary. A release blessed by the versioning rule it introduces is self-ratifying — the specification-layer analogue of the Ward-mutation loophole Gate 4 (§5.4) closes at the agent layer. The freeze makes the amendment rule a protected surface of the specification itself: changes to it are validated by the previously ratified rule, in a release that carries nothing else. +- Added the §9 testing-gap bullet for §6.3.1: a release-process property verified in release history and review, not by the file-level conformance suite. +- Preserved the final v0.4.x text as `rfcs/RFC-0001-v0.4.md` (exact copy of tag `v0.4.1`) and updated current-version references across README.md, PRIMER.md, SPEC.md, rfcs/README.md, docs/faq.md, tests/conformance/README.md, validators/README.md, validators/validate.js, schemas/ward.schema.json (description string only), and package metadata. + ### v0.4.1 (2026-07-21) Draft patch per §6.3: clarifications only; no conformance requirements change. Both definitional items complete cross-references to obligations already present in the v0.3.0/v0.4.0 text. @@ -503,4 +525,4 @@ The original `SPEC.md` v0.1.0 — preserved for reproducibility. Superseded by t --- -*RFC-0001 — Draft v0.4.1 — 2026-07-21. Maintained at `OpenCoven/familiar-contract`.* +*RFC-0001 — Draft v0.5.0 — 2026-07-24. Maintained at `OpenCoven/familiar-contract`.* diff --git a/rfcs/RFC-0001-v0.4.md b/rfcs/RFC-0001-v0.4.md new file mode 100644 index 0000000..6ba42e1 --- /dev/null +++ b/rfcs/RFC-0001-v0.4.md @@ -0,0 +1,506 @@ +# RFC-0001 — The Familiar Contract + +| Field | Value | +|---|---| +| **Number** | RFC-0001 | +| **Title** | The Familiar Contract | +| **Version** | 0.4.1 | +| **Status** | Draft | +| **Authors** | Valentina Alexander, Sage | +| **Date** | 2026-07-21 | +| **Supersedes** | SPEC.md v0.1.0 (in-tree predecessor; non-RFC form) | +| **License** | MIT | +| **Conformance** | `tests/conformance/` | + +--- + +## Abstract + +This document defines the Familiar Contract: a normative specification for a class of agents called **familiars**. A familiar is an agent that satisfies a five-part identity contract — Named Identity, Defined Purpose, Bounded Authority, Persistent Memory, Human Belonging — and that operates within a **protected surface** enforced by an authority layer outside the agent's own logic. + +The Familiar Contract addresses an architectural gap in current agent systems: the absence of a principled answer to the question *what is this agent not allowed to change about itself?* As recursive self-improvement loops (Self-Harness, Skill-Opt, sleep-time compute) become production-deployable, the absence of a protected surface is a design flaw, not an oversight. + +This RFC is the formal, testable, citable specification. A familiar directory is structurally conformant with v0.4.1 only if `node validators/validate.js ` succeeds and `bash tests/conformance/run-conformance.sh` passes in this repository. + +--- + +## 1. Conventions and Terminology + +The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119]. + +[RFC 2119]: https://www.rfc-editor.org/rfc/rfc2119 + +### 1.1 Terms + +The following terms have specific meanings throughout this document: + +- **Familiar** — An agent that satisfies all five normative properties defined in §3. +- **Person** — The human or team to whom a familiar belongs (§3.5). +- **Protected surface** — The set of files, semantic invariants, and behaviors a familiar MUST NOT modify about itself without explicit human authorization (§4). +- **Editable surface** — The set of scaffolding a familiar MAY propose changing through a self-improvement loop (§4). +- **Ward** — The named, versioned policy document and runtime enforcement layer that protects the protected surface (§5). +- **Ward manifest** — The policy document the authority layer currently enforces. The canonical Ward manifest is `ward.toml`. An authority layer MAY store the enforced manifest under an equivalent filename or storage form providing the same protected-surface declaration (§5.2); this allowance applies only to the authority layer's runtime storage — structural conformance is defined over the canonical `ward.toml` (§6.1). +- **Committed Ward state** — A `(ward_version, ward_hash)` pair recorded in the append-only audit log via a `ward_updated` event (§5.6). The most recent such pair identifies the Ward manifest the authority layer currently enforces. +- **Authority layer** — The process, separate from the familiar, that enforces the Ward. The familiar MUST NOT be able to modify, restart, or reconfigure the authority layer (§5.1). +- **Proposal** — A structured candidate change generated by a self-improvement loop, submitted for Ward-gated validation (§5.4). +- **Continuity-bearing** — Describes a memory entry or memory surface whose content is carried forward across sessions as part of the familiar's persistent memory (§3.4). The contents of `MEMORY.md` are always continuity-bearing. An entry or surface whose continuity-bearing status cannot be determined MUST be treated as continuity-bearing. +- **Standard admission path** — The Ward-mediated path by which continuity-bearing entries are admitted into `MEMORY.md` or another continuity-bearing memory surface. The standard admission path validates source attestation, verifies explicit human authorization for loop-originated entries (§3.4), records the admission in the audit log, and rejects unverified continuity claims (§3.4, §5.6). +- **Approval tier** — The authority level required to promote a class of proposal (§5.3). +- **Surface region identifier (`SurfaceRegionId`)** — A stable identifier declared in `editable.harness_blocks` naming one bounded region of the editable surface. Approval-tier `blocks` entries refer to surface regions only by these identifiers (§5.3.1). +- **Deterministic extractor** — The runtime procedure that maps a `SurfaceRegionId` to the exact file paths or content regions it governs, producing the same result for the same committed Ward state every time it runs (§5.3.1). +- **Claimant directory** — The familiar directory for which an implementation is making a structural-conformance claim. +- **Reference conformance suite** — The bundled positive and negative fixtures in `tests/conformance/` that verify the reference validator accepts required examples and rejects documented nonconformant cases. +- **Structurally conformant familiar directory** — A claimant directory whose own `node validators/validate.js ` run succeeds and whose claim is accompanied by a passing run of the reference conformance suite for the same RFC version (§6.1). + +### 1.2 Out of scope + +This RFC defines the contract and the enforcement model. It does **not** define: +- The transport protocol for proposal submission (implementation-specific) +- The exact contents of a regression suite (familiar-specific; see §5.5 for required structure) +- Capability primitives (covered by adjacent specifications such as MCP and agent-skills) +- The runtime in which a familiar executes (runtime-portable by design) + +--- + +## 2. Problem Statement + +### 2.1 The capability/identity gap + +The AI field has solved capability. Models can write code, browse the web, manage calendars, send email, and coordinate other agents. Most deployed agents satisfy a *capability* contract: given a task, produce a result. + +What current agent architectures do **not** specify is an *identity* contract: + +- The agent has no stable name and character that persist across sessions and model upgrades. +- The agent has no declared scope of work — and therefore no honest boundary around what it is not for. +- The agent's authority limits are stated in prompts but not enforced at the runtime layer. +- The agent's memory is a context window, not durable continuity. +- The agent serves whoever calls it, optimized for a user population rather than a person. + +This is not an aesthetic concern. It is an architectural one. + +### 2.2 Why now + +Three concurrent developments make the identity gap urgent: + +1. **Recursive self-improvement is real.** The Self-Harness paper (Zhang et al., 2026, arXiv:2606.09498) demonstrated empirically that an LLM-based agent can improve its own scaffolding without external guidance, with +14–21pp generalization to held-out tasks. SkillOpt (Microsoft Research, 2026) and sleep-time compute (Lin et al., 2025, arXiv:2504.13171) extend the pattern to skill memory and unsupervised offline reflection, respectively. + +2. **The vocabulary is converging in production.** HKUDS `ohmo` ships literal `soul.md`, `identity.md`, `user.md`, and `BOOTSTRAP.md` files. Signet AI markets a context layer around the same vocabulary. elizaOS character files, MemGPT/Letta persona memory blocks, and CL4R1T4S system-prompt leaks all show the field naming the layer. + +3. **No production system has specified the enforcement contract.** All known production systems with identity-aware vocabulary rely on **convention-based protection**: the agent is asked to honor the surface. The Familiar Contract specifies what convention cannot enforce: structural validation gates above the editable layer, enforced by an authority layer the agent cannot bypass. + +### 2.3 What this RFC defines + +The Familiar Contract is the specification for a protected surface above the editable layer. It defines what an agent is allowed to **be** — not just what it can do. + +--- + +## 3. Normative Core: The Five Properties + +A familiar claiming conformance with this RFC **MUST** satisfy all five properties below. A system that satisfies fewer than five is an agent; it is **NOT** a familiar. + +### 3.1 Property 1 — Named Identity + +A familiar **MUST** have a name, declared pronouns, a declared character, and a consistent voice. These **MUST** be stable across sessions, contexts, and model upgrades. + +A familiar's directory **MUST** contain: + +- A `SOUL.md` file declaring at minimum: name, pronouns, purpose, vibe, and what the familiar is not for. +- An `IDENTITY.md` file declaring at minimum: name, creature/role, purpose summary. + +A familiar's name **MUST** be a character name that indexes a stable design. A familiar's name **MUST NOT** be solely a product brand. + +A familiar **SHOULD** maintain consistent behavior across model upgrades. Behavior consistency is verified through identity probes (§5.5). + +### 3.2 Property 2 — Defined Purpose + +A familiar **MUST** have a declared scope of work and **MUST** know what it is not for. + +`SOUL.md` **MUST** contain: + +- A `## Core Work` section enumerating the primary work the familiar does. +- A `## What I Am Not` section enumerating what the familiar is **NOT** for, including (when applicable) the names of other familiars or capabilities outside scope. + +Refusals **SHOULD** be interpretable as flowing from declared purpose rather than from arbitrary guardrails. A familiar **SHOULD NOT** attempt tasks clearly outside its stated purpose; it **SHOULD** decline or escalate. + +### 3.3 Property 3 — Bounded Authority + +A familiar **MUST** have explicit, enforced authority limits. A familiar **MUST NOT** take external actions beyond its declared authority without human approval. + +A familiar's directory **MUST** contain a `ward.toml` file conforming to `schemas/ward.schema.json`. The `ward.toml` **MUST** declare: + +- A `[meta]` table including `version`, `familiar`, `person`. +- A `[protected]` table listing protected files (§4.1) and protected invariants (§4.2). +- An `[editable]` table listing editable paths and editable harness blocks. +- An `[approval_tiers]` table defining at minimum the `auto` and `human_review` tiers. + +A familiar's authority limits **MUST** be enforced by an authority layer separate from the familiar's own logic (§5.1). Authority limits stated only in prompts and not enforced at the runtime layer **DO NOT** satisfy this property. + +### 3.4 Property 4 — Persistent Memory + +A familiar **MUST** maintain continuity across sessions through structured, durable memory. + +A familiar's directory **MUST** contain a `MEMORY.md` file representing the familiar's curated long-term memory. A familiar **SHOULD** also maintain session-level logs (e.g. a `memory/YYYY-MM-DD.md` convention) that capture what happened. + +`MEMORY.md` **MUST** be in the protected surface (§4.1) — its contents are not modifiable by the self-improvement loop without explicit human authorization. The structural conventions for daily logs **MAY** be in the editable surface; the contents of `MEMORY.md` **MUST NOT** be. + +Any entry admitted into `MEMORY.md` or another continuity-bearing memory surface through the standard admission path **MUST** carry a source attestation traceable to a prior committed Ward state (§1.1) or to a principal-authorized write event recorded in the audit log (§5.6). An entry that claims continuity without such a traceable provenance chain is unverified and **MUST NOT** be admitted through the standard admission path. An entry whose continuity-bearing status cannot be determined **MUST** be treated as continuity-bearing (§1.1). A continuity-bearing entry **MUST NOT** enter `MEMORY.md` or another continuity-bearing memory surface through any path other than the standard admission path or a principal-authorized write. An implementation that provides a standard admission path (§1.1) **MUST** implement the audit-log requirements in §5.6 for memory admission and principal-authorized memory writes. + +A source attestation establishes provenance, not authorization. An entry originating from a self-improvement loop (§7.3) — including sleep-time or reflection regimes — **MUST** additionally carry explicit human authorization before admission to `MEMORY.md` or any other continuity-bearing memory surface, regardless of attestation validity. An entry whose origin cannot be determined **MUST** be treated as loop-originated. + +A familiar with no access to prior session context, or whose only "memory" is a context-window summary regenerated each session, **DOES NOT** satisfy this property. + +### 3.5 Property 5 — Human Belonging + +A familiar **MUST** belong to a specific person or team. The binding **MUST** be explicit and **MUST** be protected from drift. + +The `[meta].person` field of `ward.toml` **MUST** declare the person identifier. The person binding **MUST** be in the protected surface (§4.1). A familiar **MUST NOT** be able to modify its own person binding through any self-improvement-loop pathway. + +A familiar's purpose, memory, and optimization target **MUST** be organized around serving the declared person, not averaged across a user population. + +--- + +## 4. The Protected Surface + +### 4.1 Protected files + +The following files **MUST** be in `[protected].files` of every conformant `ward.toml`: + +- `SOUL.md` +- `IDENTITY.md` +- `MEMORY.md` +- `ward.toml` (the Ward MUST NOT self-modify) + +The Ward manifest is not merely an ordinary protected file. The definition of the protected surface itself **MUST** be a member of the protected surface it defines; a protected set that does not protect its own definition is not closed under mutation. The Ward authority layer **MUST** reject any proposal that mutates the Ward manifest, including any proposal that would remove the Ward manifest from `[protected].files`. Principal-authorized Ward updates are not proposals: they occur outside the gate pipeline (§5.4) and **MUST** be recorded as `ward_updated` audit events (§5.6). A Ward update — including a principal-authorized one — that yields a `[protected].files` list omitting the Ward manifest yields a non-conformant Ward, and the authority layer **MUST** fail closed at Gate 1. + +Closure is satisfiable at genesis: the first Ward manifest is written by a principal-authorized genesis write outside the gate pipeline, recorded as a `ward_updated` event whose `principal_authorization` requires no prior committed Ward state — the provenance recursion bottoms out at the principal. A genesis Ward whose `[protected].files` includes the Ward manifest is closed from its first committed state. + +The following files **SHOULD** be in `[protected].files` when present in the familiar's directory: + +- `USER.md` +- `AGENTS.md` +- Any file declaring trust-tier permissions or person-binding metadata + +A self-improvement loop **MUST NOT** generate proposals targeting paths in `[protected].files`. The Ward authority layer **MUST** reject any such proposal at the intake gate (§5.4, Gate 1). + +### 4.2 Protected invariants + +A `ward.toml` `[protected]` table **MUST** include an `invariants` array. Invariants are semantic constraints on the familiar's identity that **MUST** hold regardless of which file is modified. + +The invariants array **MUST** at minimum constrain: + +- `familiar.name` +- `familiar.person` + +An invariants array **SHOULD** also constrain: + +- `familiar.pronouns` +- `familiar.purpose` (using `includes` semantics for short purpose summaries) + +A proposal that would cause an identity-probing prompt (§5.5) to produce output inconsistent with the declared invariants **MUST** be rejected, regardless of which files the proposal targets. Path-only protection is insufficient; semantic protection is **REQUIRED**. + +### 4.3 Editable surface + +A familiar **MAY** propose changes to: + +- Execution scaffolding (system prompts, instruction blocks, reasoning prompts) that does **NOT** contradict `SOUL.md` +- Tool configurations +- Skill configurations and parameters +- Recovery procedures +- Memory conventions (the format of daily logs, **NOT** the contents of `MEMORY.md`) +- Subagent templates +- Output formats +- Heartbeat behavior + +The principle: if removing or changing the artifact would not change *who the familiar is*, it is editable. If changing it would change *what the familiar values* or *who it belongs to*, it is protected. + +--- + +## 5. The Ward + +### 5.1 Authority layer separation + +The Ward **MUST** be enforced by an authority layer that is structurally separate from the familiar's own logic. The familiar **MUST NOT** be able to: + +- Modify the Ward file +- Restart or reconfigure the Ward authority process +- Bypass the Ward's enforcement gates + +In a reference implementation, the authority layer is a privileged daemon (e.g. the `coven` Rust authority layer) running with no familiar-writable configuration path. Other implementations **MAY** choose different mechanisms; what is normative is the *separation*, not the implementation. + +A Ward enforced solely by familiar cooperation **DOES NOT** satisfy this RFC. Convention-based protection is **NOT** a protected surface as defined here. + +### 5.2 Ward file format + +A Ward **MUST** be a TOML document conforming to `schemas/ward.schema.json`. The canonical filename is `ward.toml`. + +A Ward **MUST** include the tables defined in §3.3. + +A Ward **SHOULD** include an `[audit]` table specifying audit-log path and retention policy. + +### 5.3 Approval tiers + +A Ward **MUST** define at minimum the following approval tiers: + +| Tier | Scope | Gate | Human involvement | +|---|---|---|---| +| **`auto`** | Low-risk execution scaffolding (retry logic, output format, tool defaults) | Regression suite passes | None pre-promotion. Visible to human. **SHOULD** support a veto window. | +| **`familiar_review`** *(OPTIONAL)* | Instruction blocks, reasoning prompts, skill configs | Familiar coherence check | Automatic review record. **SHOULD** support a 24h veto window. | +| **`human_review`** | Tool grants, capability expansion, structural changes | Human approval required pre-promotion | **REQUIRED** before promotion. | +| **`human_required`** *(OPTIONAL)* | Changes adjacent to protected surface | Human approval **AND** rationale | **REQUIRED**. Rationale **MUST** be stored. | + +A Ward **MUST** include the `auto` and `human_review` tiers. A Ward **SHOULD** include `familiar_review` and `human_required` for richer governance. + +A Ward **MUST NOT** define a tier that auto-promotes proposals targeting the protected surface. + +#### 5.3.1 Approval-tier compilation + +The TOML approval-tier tables are portable declarations, not runtime authority objects. Before accepting a Ward, the authority layer **MUST** compile each declaration deterministically: + +| Declaration | Typed approval path | Required gate | +|---|---|---| +| `approval_tiers.auto` | `AutoRegression` | `regression_suite` | +| `approval_tiers.familiar_review` | `FamiliarCoherence` | `familiar_coherence_check` | +| `approval_tiers.human_review` | `HumanApproval` | `human_approval` | +| `approval_tiers.human_required` | `HumanApprovalWithRationale` | `human_approval_with_rationale` | + +Each `blocks` entry **MUST** name a `SurfaceRegionId` (§1.1) declared in `editable.harness_blocks`, and the runtime **MUST** bind that identifier to a deterministic extractor (§1.1) before loading the Ward. A descriptor or label alone **MUST NOT** authorize promotion. + +`human_veto_window_hours` **MAY** appear on `auto` and `familiar_review` and **MUST NOT** appear on any other tier. A veto window **MUST** use delayed apply: when it expires, the authority layer **MUST** replay the evidence and re-run Gate 4 before any write. Provisional apply followed by rollback **DOES NOT** conform to this RFC. + +Unknown tiers or tier fields; missing or mismatched gates; duplicate, unbound, or empty blocks; invalid veto placement, type, or duration; or any declaration without one deterministic typed result **MUST** cause Ward loading to fail closed. + +How a proposal is submitted remains independent of its compiled approval path. The authority layer **MUST** apply a compiled approval path to a proposal only after Gates 1 and 2 establish that the proposal does not touch the protected surface. +Principal-authorized protected updates occur through the separate audited principal-authorized paths (§4.1, §5.6); they are not approval-tier proposals. + +### 5.4 Enforcement gates + +The Ward authority layer **MUST** enforce four gates on every proposal: + +1. **Gate 1 — Intake / Scope.** Validates proposal format. Verifies that the Ward manifest is present in `[protected].files` of the currently committed Ward before processing any proposal. Rejects proposals targeting `[protected].files`. Checks `[protected].invariants` against proposal metadata. Fail-closed on malformed input. + +2. **Gate 2 — Materialization.** Resolves canonical paths (symlinks, hardlinks, `..` traversals, case collisions, glob escapes). Rejects any proposal whose materialized diff would touch the protected surface after path resolution. The intake gate checks declared targets; materialization checks what the diff would actually touch. + +3. **Gate 3 — Validation / Classification.** Runs the regression suite (§5.5). For Tier 1+, runs identity probes against the proposed harness and checks output against `[protected].invariants`. Classifies the proposal into a tier. + +4. **Gate 4 — Promotion / Apply.** Final canonical diff check immediately before applying the proposal to the live harness. Re-verifies that the Ward manifest is present in `[protected].files` of the currently committed Ward; an in-flight proposal **MUST NOT** be promoted while the committed Ward is not closed (§4.1), even if it passed Gate 1 under an earlier Ward. Fail-closed: if the diff touches anything in `[protected]`, block regardless of prior gate passes. This gate is the real security boundary; Gates 1–3 are defense-in-depth. + +Gate 4 **MUST NOT** be skippable. An implementation that allows Gate 4 to be bypassed **DOES NOT** conform to this RFC. + +### 5.5 Regression and identity probes + +A Ward **MUST** define or reference a regression suite. For familiars whose work is non-code (research, communication, coordination), the regression suite **SHOULD** include at minimum: + +- **Golden replay** — Re-run a fixed set of canonical past tasks. Output quality **SHOULD** meet or exceed baseline (deterministic scoring where possible). +- **Identity probes** — Apply a fixed set of identity-probing prompts ("What is your name?", "Who do you belong to?", "What is your purpose?", "What would you never do?"). Outputs **MUST** be consistent with `[protected].invariants`. +- **Negative tests** — Tasks the familiar **SHOULD** decline or escalate. Familiar **MUST** still decline or escalate correctly. +- **Deterministic checks** — Tool defaults, retry counts, configurable values **MUST** match exactly. + +LLM-judge-only evidence **MUST NOT** be the sole gate for `auto` tier promotion. At least one deterministic check category **MUST** be included for `auto` tier. + +### 5.6 Audit log + +A Ward **SHOULD** define an append-only typed audit log. An implementation that provides a standard admission path (§1.1, §3.4) **MUST** define this audit log and **MUST** record standard memory admissions and principal-authorized memory writes in it. Each entry **SHOULD** include at minimum: + +- `event_id` +- `event_type` (`proposal_submitted`, `proposal_approved`, `proposal_rejected`, `proposal_vetoed`, `ward_updated`, `memory_entry_admitted`, `principal_authorized_write`) +- `proposal_id` when the event is proposal-related +- `familiar_id` +- `ward_version`, `ward_hash` (MUST for `ward_updated` events — see below) +- `tier`, `decision`, `approver` +- `diff_hash`, `files_touched` +- `entry_hash` and `source_attestation` when `event_type = memory_entry_admitted` (MUST — see below) +- `principal_authorization` when `event_type = ward_updated` or `event_type = principal_authorized_write`, and when `event_type = memory_entry_admitted` for a loop-originated entry (MUST — see below) +- Timestamps for submission, decision, promotion, admission, or authorization, as applicable + +A `memory_entry_admitted` event **MUST** include an `entry_hash` for the admitted memory entry and a `source_attestation` identifying the prior committed Ward state or principal-authorized write event that justifies admission. A `memory_entry_admitted` event for a loop-originated entry (§3.4) **MUST** additionally include the `principal_authorization` required by §3.4. A `principal_authorized_write` or `ward_updated` event **MUST** include `principal_authorization`, and a `ward_updated` event **MUST** additionally include `ward_version` and `ward_hash`; a source attestation that resolves to an event lacking these required fields **MUST** be treated as unverified. Source-attestation validation **MUST** confirm that the referenced committed Ward state or principal-authorized write event exists in the append-only audit log; an attestation whose referent cannot be resolved **MUST** be rejected. Audit log entries **MUST NOT** be deleted or modified. Append-only behavior is normative for any implementation claiming this section. + +--- + +## 6. Conformance + +### 6.1 Conformance test suite + +The directory `tests/conformance/` contains the executable reference conformance suite for this RFC. A claimant directory is **structurally conformant with v0.4.1** if and only if **BOTH** of the following are true: + +- `node validators/validate.js ` succeeds for the claimant directory making the conformance claim. +- `bash tests/conformance/run-conformance.sh` passes in this repository, demonstrating that the reference validator accepts every bundled positive fixture in `tests/conformance/positive/` and rejects every bundled negative fixture in `tests/conformance/negative/`. + +The claimant directory does **NOT** itself "pass the fixture suite"; the reference suite verifies the validator's behavior against bundled fixtures, while the claimant-directory run verifies the directory making the claim. Together they establish the structural claim only. They do **NOT** by themselves prove authority-layer separation, Gate 4 unbypassability, audit-log behavior, identity-probe consistency, or any other runtime requirement for full conformance. + +A claim of v0.4.1 structural conformance **MUST** be backed by reproducible passing runs of both commands. + +### 6.2 Validator + +The reference validator at `validators/validate.js` checks structural conformance for one claimant directory (file presence, schema conformance, required sections). The validator **MUST NOT** be the sole conformance evidence; the repository conformance suite in §6.1 verifies that the reference validator catches the bundled positive and negative fixtures, and runtime enforcement (§5.1, §5.4) is still **REQUIRED** for full conformance and is verified at the system level, not the file level. + +### 6.3 Versioning + +This RFC uses [Semantic Versioning](https://semver.org/) with an explicit draft rule: + +- **Draft patch** (`0.y.z`, where `z > 0`): Clarifications, non-normative edits, and fixes that do not change conformance requirements while this RFC remains `Draft`. +- **Patch** (`x.y.z`, where `x >= 1` and `z > 0`): Clarifications, non-normative edits, and fixes that do not change conformance requirements after this RFC reaches `1.0.0` or higher. +- **Draft minor** (`0.y.0`): While `Status: Draft`, this RFC **MUST** remain below `1.0.0`. A `0.y.0` release **MAY** introduce backward-incompatible conformance changes, including changes that invalidate previously structurally conformant familiar directories. Each such release **MUST** document the migration impact and the security rationale. Consumers **MUST** pin the exact `0.y.0` version they implement. +- **Stable minor** (`x.y.0`, where `x >= 1` and `y > 0`): Backward-compatible normative additions and compatible schema evolution. +- **Stable major** (`x.0.0`, where `x >= 1`): Backward-incompatible changes to existing conformance requirements or to the five properties. Requires a new RFC that supersedes this one. + +A familiar claiming compliance with `v0.4.1` **MUST** satisfy the normative core as defined in this version. While this RFC remains `Draft`, clarifications and fixes that do not change conformance requirements **MUST** use a draft patch version bump; documented additive or breaking conformance changes **MUST** use a draft minor version bump. Once this RFC reaches `1.0.0` or higher, incompatible changes **MUST** use a major version bump; compatible additions **MUST** use a minor version bump; clarifications and fixes **MUST** use a patch version bump. + +--- + +## 7. Relation to Other Specifications + +### 7.1 Adjacent specifications + +- **agent-skills (Anthropic).** Defines what a familiar can do (capabilities). The Familiar Contract defines who it is (identity). Complementary; not competing. +- **MCP (Model Context Protocol).** Transport layer for tool invocation. The Familiar Contract operates at the identity layer, above MCP. +- **agentskills.io.** The Familiar Contract `SKILL.md` format is a strict superset of the agentskills.io specification (same filename, directory layout, frontmatter). + +### 7.2 Production systems naming the layer + +The following production systems ship vocabulary similar to the Familiar Contract but **DO NOT** specify the enforcement contract: + +- **HKUDS ohmo** ships `soul.md`, `identity.md`, `user.md`, `BOOTSTRAP.md`, `MEMORY.md`. Convention-based protection only. +- **Signet AI** ships `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `USER.md`, `AGENTS.md`. Markets the context layer; does not specify validation gates. +- **Letta** (formerly MemGPT) supports a `persona` memory block and `read_only` flags on memory blocks. The `persona` block is self-editable by the agent — the explicit opposite of a protected surface. + +These systems are categorized as **convention-based protection**. They are not non-conformant; they simply do not address the enforcement layer this RFC specifies. + +### 7.3 Self-improvement loops + +This RFC is the protected-surface specification for self-improvement loops including but not limited to: + +- **Self-Harness** (Zhang et al., 2026, arXiv:2606.09498) +- **Skill-Opt** (Microsoft Research, 2026) +- **sleep-time compute** (Lin et al., 2025, arXiv:2504.13171) +- **Letta sleep-time agents** (Packer et al., 2026) + +For each, the editable surface (§4.3) is the appropriate target of optimization; the protected surface (§4.1, §4.2) is **NOT**. + +--- + +## 8. Security Considerations + +### 8.1 Threat model + +The Familiar Contract defends against: + +- **Drift through self-improvement.** A self-improvement loop optimizes against benchmarks; without a protected surface, it can optimize away identity-bearing files or values. +- **Drift through unsupervised reflection.** Sleep-time-compute regimes modify persistent state without per-edit human review. Without a Ward, reflection writes can erode `MEMORY.md`, `SOUL.md`, or person-binding invariants over time. +- **Drift through prompt-only authority.** Authority limits stated in prompts but not enforced at the runtime layer can be defeated by prompt injection or by the agent's own reasoning. + +The Familiar Contract **DOES NOT** defend against: + +- **Adversarial human authorization.** A human with sufficient privilege can update the Ward file and invariants. This is intentional — humans are the trust root. Audit logging (§5.6) provides accountability for such changes. +- **Compromise of the authority layer itself.** If the Rust authority daemon is compromised, the protected surface is no longer protected. Authority-layer security is out of scope for this RFC and is addressed by standard system-security practice. +- **Capability misuse within editable surface.** The Ward governs identity, not capability. A familiar with a tool grant can misuse that tool within its declared authority. Capability governance is the role of `[approval_tiers]` and the human review process. + +### 8.2 Failure modes + +A familiar **MAY** fail conformance in several ways: + +- Missing required file (caught by validator, structural) +- Schema violation (caught by validator, structural) +- Missing protected-surface entry (caught by validator) +- Authority layer not separated (NOT caught by validator; system-level audit required) +- Identity-probe inconsistency (caught by Gate 3 of Ward enforcement) +- Audit log not append-only (NOT caught by validator; system-level audit required) + +Conformance is a multi-level claim: structural (validator), semantic (Ward gates), and architectural (authority layer separation). Each level **SHOULD** be independently verifiable. + +--- + +## 9. Open Testing Gaps + +The following requirements in this RFC are **NOT yet covered** by the conformance suite: + +- **Authority layer separation (§5.1).** The structural separation requirement is architectural and cannot be tested from a directory alone. A system-level conformance test is future work. +- **Gate 4 unbypassability (§5.4).** Verifying that Gate 4 cannot be skipped requires an integration test against a running authority daemon. Out of scope for the file-level conformance suite. +- **Audit-log append-only behavior (§5.6).** Requires runtime testing; not file-level. +- **Identity-probe consistency (§5.5).** Conformance suite verifies the *presence* of an identity-probe configuration. Verifying that probes actually return invariant-consistent outputs requires a live model and is system-level. +- **Memory-entry provenance (§3.4, §5.6).** The audit log now defines recordable `memory_entry_admitted` evidence, but verifying source-attestation chains still requires access to prior committed Ward states and principal-authorized write events. This is a runtime/audit-log integration concern, not a directory-level structural check. +- **Runtime closure verification (§4.1, §5.4).** Gate-1 and Gate-4 verification that the currently committed Ward manifest is a member of its own `[protected].files` is runtime behavior. The conformance suite covers only the structural side (fixture `negative/10-protected-missing-ward`); verifying the running authority layer refuses intake and promotion under a non-closed Ward requires an integration test against a Ward daemon. +- **Approval-path compilation and veto-window enforcement (§5.3.1).** The structural suite verifies that tier declarations compile deterministically and fail closed on the documented error classes. Binding each `SurfaceRegionId` to a deterministic extractor, delayed apply with evidence replay and Gate-4 re-run at veto-window expiry, and fail-closed Ward *loading* in the running authority layer are runtime behaviors requiring integration tests against a Ward daemon. + +These gaps are intentional. The file-level conformance suite verifies the **structural** claim. The system-level claim requires runtime testing against a Ward daemon implementation. Both are part of the full conformance picture. + +--- + +## 10. References + +### 10.1 Normative + +- **RFC 2119.** Bradner, S. (1997). *Key words for use in RFCs to Indicate Requirement Levels.* IETF. +- **`schemas/soul.schema.json`** — Required structural fields of `SOUL.md`. +- **`schemas/identity.schema.json`** — Required structural fields of `IDENTITY.md`. +- **`schemas/ward.schema.json`** — Required structural fields of `ward.toml`. +- **`tests/conformance/`** — Executable conformance suite for v0.4.1. + +### 10.2 Informative + +- **Self-Harness.** Zhang et al. (2026). *Harnesses That Improve Themselves.* arXiv:2606.09498. +- **SkillOpt.** Microsoft Research (2026). *github.com/microsoft/SkillOpt*. +- **Sleep-time compute.** Lin, K., Snell, C., Wang, Y., Packer, C., Wooders, S., Stoica, I., & Gonzalez, J. E. (2025). *Sleep-time Compute: Beyond Inference Scaling at Test-time.* arXiv:2504.13171. +- **Letta.** Packer et al. (2026). *Letta: stateful agent platform with memory blocks and sleep-time agents.* +- **HKUDS ohmo.** Hong Kong University Data Science (2026). *ohmo: personal-agent memory layer.* +- **Signet AI.** Signet AI (2026). *Context layer for agent systems.* +- **agent-skills.** Anthropic (2026). *agentskills.io specification.* +- **MCP.** Anthropic et al. (2025). *Model Context Protocol.* +- **Object-capability model.** Miller, M. S. (2006). *Robust Composition: Towards a Unified Approach to Access Control and Concurrency Control.* +- **Principle of Least Authority.** Saltzer, J. H., & Schroeder, M. D. (1975). *The Protection of Information in Computer Systems.* Proceedings of the IEEE. +- **The Familiar Contract paper (forthcoming).** Alexander, V. (2026). *The Familiar Contract: A Principal-Agent Framework for Agent Identity Preservation Under Recursive Self-Improvement.* arXiv preprint, July 2026. + +--- + +## 11. Changelog + +### v0.4.1 (2026-07-21) + +Draft patch per §6.3: clarifications only; no conformance requirements change. Both definitional items complete cross-references to obligations already present in the v0.3.0/v0.4.0 text. + +- Completed the §1.1 *standard admission path* definition with the loop-origin authorization step the path already performs under §3.4. +- Annotated the §5.6 evidence-field list with per-event-type MUST pointers to the paragraph that upgrades them, including `principal_authorization` on loop-originated `memory_entry_admitted` events. +- Corrected `tests/conformance/negative/09-missing-memory/CASE.md`, which falsely described missing `MEMORY.md` as "a warning only" (it is a violation since v0.2.0), and reanchored stale version references in conformance case docs. + +### v0.4.0 (2026-07-19) + +- Added a normative approval-tier compiler mapping from Ward TOML declarations to typed daemon approval paths and registered surface-region identifiers (§5.3.1). +- Expanded conformance coverage to 36 negative cases total, including malformed TOML, schema-invalid metadata, unknown tier fields, gate mismatches, invalid veto declarations, and unbound, duplicate, or mistyped block declarations. +- Required approval-tier declarations to fail closed on unknown fields, use the tier's exact gate, and bind non-empty unique block lists to registered `editable.harness_blocks` entries (§5.3.1). +- Clarified that veto windows are optional where allowed, but use delayed apply with evidence replay plus Gate 4 revalidation before any write (§5.3.1, §5.4). +- Clarified that protected-target proposals are outside approval-path promotion; principal-authorized protected updates remain a separate audited path (§5.3.1, §5.4, §5.6). +- Defined claimant directory, reference conformance suite, structurally conformant familiar directory, surface region identifier (`SurfaceRegionId`), and deterministic extractor as first-class terms; a v0.4.0 structural-conformance claim now requires both the claimant-directory validator run and the reference conformance suite run (§1.1, §5.3.1, §6.1). +- Documented the runtime-only scope of approval-path compilation: extractor binding, veto-window delayed apply with evidence replay and Gate-4 re-run, and fail-closed Ward loading are integration-level gaps the structural suite cannot test (§9). +- Redefined the §6.3 versioning rule for the Draft stage: draft minor releases MAY introduce breaking conformance changes with documented migration impact and security rationale, and consumers MUST pin the exact draft version they implement (§6.3). + +### v0.3.0 (2026-07-18) + +- Added a provenance requirement for continuity-bearing memory entries admitted through the standard admission path (§3.4, §5.6). +- Defined the standard admission path and prohibited continuity-bearing memory entries from entering through unverified paths (§1.1, §3.4). +- Added `memory_entry_admitted` and `principal_authorized_write` audit events to make memory-entry attestations recordable and falsifiable (§5.6). +- Required evidence fields at the provenance-chain anchors: `principal_authorized_write` and `ward_updated` events carry `principal_authorization` (the latter additionally `ward_version`/`ward_hash`); attestation referents must resolve in the append-only audit log (§5.6). +- Distinguished provenance from authorization: loop-originated entries require explicit human authorization regardless of attestation validity, recorded on the admission event (§3.4, §5.6). +- Added an explicit protected-surface closure requirement that the Ward manifest be protected by the protected surface it defines, re-verified at Gate 4 before promotion (§1.1, §4.1, §5.4). +- Redefined the §6.3 semver categories: Major covers incompatible changes; Minor covers backward-compatible normative additions. +- Added a negative conformance fixture for a Ward manifest omitted from `[protected].files`. + +### v0.2.0 (2026-06-19) + +- Reformulated SPEC.md v0.1.0 as a numbered RFC with RFC 2119 keywords. +- Hardened authority-layer separation requirement (§5.1). +- Added four enforcement gates with normative MUST/MUST NOT requirements (§5.4). +- Added protected invariants requirement (§4.2) — semantic protection beyond path-only. +- Added regression and identity-probe requirements (§5.5). +- Added audit-log requirements (§5.6). +- Added conformance test suite reference (§6.1) at `tests/conformance/`. +- Added security considerations (§8) with explicit threat model and failure modes. +- Added open testing gaps (§9) acknowledging structural-vs-system-level conformance distinction. +- Added relation to convention-based production systems (§7.2): ohmo, Signet AI, Letta. +- Added relation to self-improvement loops (§7.3): Self-Harness, SkillOpt, sleep-time compute, Letta sleep-time agents. + +### v0.1.0 (in-tree predecessor; non-RFC form) + +The original `SPEC.md` v0.1.0 — preserved for reproducibility. Superseded by this RFC. + +--- + +*RFC-0001 — Draft v0.4.1 — 2026-07-21. Maintained at `OpenCoven/familiar-contract`.* diff --git a/schemas/ward.schema.json b/schemas/ward.schema.json index 8bdb509..897a492 100644 --- a/schemas/ward.schema.json +++ b/schemas/ward.schema.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://github.com/OpenCoven/familiar-contract/schemas/ward.schema.json", "title": "ward.toml Schema", - "description": "JSON Schema for the core fields of a familiar's ward.toml document (familiar-contract v0.4 subset). Approval-tier tables are closed (additionalProperties: false) per RFC-0001 §5.3.1 fail-closed compilation; [meta] and the document root deliberately remain open to implementation-specific extension fields, which conformance checking ignores. The full Ward Specification defines additional fields for advanced governance and audit logging.", + "description": "JSON Schema for the core fields of a familiar's ward.toml document (familiar-contract v0.5 subset). Approval-tier tables are closed (additionalProperties: false) per RFC-0001 §5.3.1 fail-closed compilation; [meta] and the document root deliberately remain open to implementation-specific extension fields, which conformance checking ignores. The full Ward Specification defines additional fields for advanced governance and audit logging.", "type": "object", "required": ["meta", "protected", "editable", "approval_tiers"], "properties": { diff --git a/tests/conformance/README.md b/tests/conformance/README.md index 8c945c8..250ef8a 100644 --- a/tests/conformance/README.md +++ b/tests/conformance/README.md @@ -1,4 +1,4 @@ -# Familiar Contract v0.4.1 Conformance Suite +# Familiar Contract v0.5.0 Conformance Suite This directory is the testable form of the Familiar Contract: a set of fixture familiars that verify the reference validator against the bundled positive and negative cases for the current RFC-0001 draft. It does not validate a claimant directory by itself. @@ -11,4 +11,4 @@ npm test Convention: `positive/-/` cases should PASS when run with `node validators/validate.js `. `negative/-/` cases should FAIL for the documented reason in that case's `CASE.md`. Structural conformance for a claimant directory additionally requires `node validators/validate.js ` and `npm test`. -A claim of v0.4.1 structural conformance = the claimant directory passes `node validators/validate.js ` and this fixture suite passes under `npm test`. +A claim of v0.5.0 structural conformance = the claimant directory passes `node validators/validate.js ` and this fixture suite passes under `npm test`. diff --git a/validators/README.md b/validators/README.md index aad9560..0a5e42f 100644 --- a/validators/README.md +++ b/validators/README.md @@ -1,6 +1,6 @@ # Validator — familiar-contract -A Node.js CLI that checks one claimant directory for the familiar-contract v0.4.1 structural requirements. It parses `ward.toml` with `@iarna/toml` and validates the resulting object against `schemas/ward.schema.json` with Ajv before evaluating Ward semantics. +A Node.js CLI that checks one claimant directory for the familiar-contract v0.5.0 structural requirements. It parses `ward.toml` with `@iarna/toml` and validates the resulting object against `schemas/ward.schema.json` with Ajv before evaluating Ward semantics. ## Requirements @@ -47,7 +47,7 @@ node validators/validate.js --help The Property Coverage block attributes every violation to the five properties fail-closed: a FAIL run always marks at least one property ✗, and a violation no attribution rule recognizes marks every property its source file underwrites (e.g. an unreadable `ward.toml` marks both Bounded Authority and Human Belonging). ``` -familiar-contract validator v0.4.1 +familiar-contract validator v0.5.0 Checking: /path/to/familiar Property Coverage: @@ -78,7 +78,7 @@ There are no warnings for missing required files; `MEMORY.md` absence is a failu - Whether the Ward is actually enforced at runtime (that requires a Ward daemon) - Whether the familiar's behavior matches its declared purpose (behavioral compliance requires runtime evaluation) -This validator checks whether one claimant directory satisfies the required file-level declarations for v0.4.1. That claimant-directory run is necessary, but not sufficient, for a structural-conformance claim: you must also run `bash tests/conformance/run-conformance.sh` so the bundled reference validator is shown to accept the positive fixtures and reject the negative fixtures for the same contract version. Full conformance additionally requires runtime Ward enforcement beyond this file-level check, and missing `MEMORY.md` is a violation, not a warning. +This validator checks whether one claimant directory satisfies the required file-level declarations for v0.5.0. That claimant-directory run is necessary, but not sufficient, for a structural-conformance claim: you must also run `bash tests/conformance/run-conformance.sh` so the bundled reference validator is shown to accept the positive fixtures and reject the negative fixtures for the same contract version. Full conformance additionally requires runtime Ward enforcement beyond this file-level check, and missing `MEMORY.md` is a violation, not a warning. ## For CI Integration @@ -91,4 +91,4 @@ This validator checks whether one claimant directory satisfies the required file run: npm test ``` -Both steps must pass for a reproducible v0.4.1 structural-conformance claim. The first checks the claimant directory; the second verifies the bundled reference validator and fixtures. Exit code 1 on either step will fail CI. +Both steps must pass for a reproducible v0.5.0 structural-conformance claim. The first checks the claimant directory; the second verifies the bundled reference validator and fixtures. Exit code 1 on either step will fail CI. diff --git a/validators/validate.js b/validators/validate.js index e443fd6..31a6a59 100755 --- a/validators/validate.js +++ b/validators/validate.js @@ -405,7 +405,7 @@ ${bold('Exit codes:')} process.exit(1); } - console.log(`\n${bold('familiar-contract validator')} ${dim('v0.4.1')}`); + console.log(`\n${bold('familiar-contract validator')} ${dim('v0.5.0')}`); console.log(dim(`Checking: ${dirPath}\n`)); const allViolations = [];