OpenCoven · BunsDev · Jul 22, 2026 · Jul 18, 2026 · Jul 20, 2026 · Jul 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+node_modules/
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,8 +32,9 @@ pull requests against this repo. This is the agent-specific layer; read
 - **Validate before you submit.** Every JSON Schema must be valid, and every
   example/fixture in the repo must validate against its schema:
   ```sh
-  # example — use whatever validator the repo scripts provide
-  find schemas -name '*.schema.json' -print0 | xargs -0 -n1 <json-schema-validate>
+  npm install
+  node -e "for (const f of require('fs').readdirSync('schemas')) JSON.parse(require('fs').readFileSync('schemas/' + f, 'utf8'))"
+  npm test
   ```
 - **Backward compatibility matters.** The contract is consumed by real agents.
   Prefer additive changes; a breaking change to identity/role/soul/ward needs an

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,42 @@ This project uses [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.4.0] — 2026-07-19
+
+### Added
+
+- **RFC-0001 §5.3.1** — Added a normative approval-tier compiler mapping from Ward TOML declarations to typed daemon approval paths and registered surface-region identifiers.
+- **tests/conformance/** — Expanded approval-tier 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.
+
+### Changed
+
+- **RFC-0001 §5.3.1** — Tier declarations now fail closed on unknown fields and require the tier's exact gate plus non-empty, unique block lists bound to registered `editable.harness_blocks` entries.
+- **RFC-0001 §5.3.1 / §5.4** — Veto windows remain optional where allowed, but use delayed apply with evidence replay plus Gate 4 revalidation before any write.
+- **RFC-0001 §5.3.1 / §5.4** — Protected-target proposals are explicitly outside approval-path promotion; principal-authorized protected updates remain a separate audited path.
+- **README.md, rfcs/README.md, SPEC.md, docs/faq.md, tests/conformance/README.md, validators/README.md, validators/validate.js** — Updated current-version references to v0.4.0.
+- **validators/validate.js** — Replaced the hand-written Ward parser with standards-compliant TOML parsing and Ajv JSON Schema validation before semantic checks.
+- **RFC-0001 §1.1 / §6.1** — 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.
+- **RFC-0001 §9** — Added an open-gap bullet for approval-path compilation: extractor binding, veto-window delayed apply with evidence replay and Gate-4 re-run, and fail-closed Ward loading are runtime behaviors outside the structural suite.
+- **examples/, tests/conformance/positive/** — Updated `examples/minimal`, `examples/sage`, and positive fixtures 01–05 `ward.toml` files to declare `editable.harness_blocks` and bind tier `blocks` to registered entries (minimal also drops `system_prompt.recovery`), keeping the suite green across the breaking declaration change.
+- **RFC-0001 §6.3** — Redefined the 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.
+
+### Migration
+
+Upgrading from v0.3.0 to v0.4.0 can invalidate previously accepted Ward declarations. Before compiling or deploying v0.4.0:
+
+1. Declare `editable.harness_blocks`.
+2. Ensure every tier block is a nonempty, unique string registered in `editable.harness_blocks`.
+3. Use the tier's exact gate for promotion; do not infer or alias gates.
+4. Remove unknown tier fields and unknown tier tables.
+5. Allow `human_veto_window_hours` only on `auto` and `familiar_review`, and only as a positive integer.
+6. Run `npm install`, then validate the Ward before upgrading.
+
+### Security rationale
+
+Prior v0.3-style ignored, ambiguous, or stringly typed declarations could create policy drift or bypasses. The v0.4 validator now rejects malformed TOML and schema-invalid values before semantic compilation, forcing deterministic, fail-closed authority declarations.
+
+---
+
 ## [0.3.0] — 2026-07-18
 
 ### Added
@@ -63,7 +99,7 @@ This project uses [Semantic Versioning](https://semver.org/).
 The RFC is now the canonical citation target:
 
 > Familiar Contract RFC-0001 v0.2.0, "The Familiar Contract."
-> OpenCoven, 2026. https://github.com/OpenCoven/familiar-contract/blob/main/rfcs/RFC-0001-familiar-contract.md
+> OpenCoven, 2026. https://github.com/OpenCoven/familiar-contract/blob/main/rfcs/RFC-0001-v0.2.md
 
 For academic citation, the tagged release at `v0.2.0` provides a stable URL.
 

diff --git a/FAQ.md b/FAQ.md
@@ -1,124 +1,5 @@
-# Frequently Asked Questions
+# Legacy FAQ pointer
 
----
+The current canonical FAQ lives at [`docs/faq.md`](docs/faq.md).
 
-### Is this a framework?
-
-No. It is a specification.
-
-The Familiar Contract defines what a compliant familiar must satisfy. It does not tell you *how* to implement it — that is for you and your runtime. Think EIP-20: the spec says a token must have `name()`, `transfer()`, and `balanceOf()`. It does not specify the Solidity version, the deployment toolchain, or the gas optimization strategy.
-
-Implement the five properties however your stack supports. What matters is whether a familiar claims compliance and actually satisfies the normative core.
-
----
-
-### What runtimes does it support?
-
-All of them. The spec is runtime-portable by design.
-
-The Familiar Contract operates at the identity and governance layer. It defines what files must exist (`SOUL.md`, `IDENTITY.md`, `ward.toml`), what fields they must contain, and what behaviors the familiar must maintain. It says nothing about which LLM, which orchestration library, which harness format.
-
-Tested against: Claude Code, Codex, Cursor, OpenHands, and the OpenCoven runtime (`openclaw`). No special runtime required.
-
----
-
-### What's the difference between a familiar and an agent?
-
-An agent is a capability primitive: it can use tools, take actions, orchestrate sub-tasks. An agent's identity is usually incidental — it has a system prompt, maybe a name, but no stable character that persists across contexts.
-
-A familiar is an identity that runs on an agent substrate. It has a stable name, defined purpose, explicit authority limits, persistent memory, and a binding to a specific person. Remove the identity layer and you have an agent. Add the identity layer and you have a familiar.
-
-The distinction is architectural. Familiars require different design choices: durable memory stores, enforcement mechanisms for authority bounds, protected surfaces for identity files, person-binding protocols. These are not prompt engineering choices. They are systems choices.
-
----
-
-### What is the Ward?
-
-The Ward is the enforcement mechanism for the Familiar Contract's protected surface.
-
-A familiar cannot be trusted to protect its own `SOUL.md` voluntarily — especially in a self-improvement loop, where the loop's goal is to modify the harness. The Ward is the authority layer that stands between the self-improvement loop and the protected surface.
-
-A Ward is a `ward.toml` file that declares which files are protected, which are editable, and what approval is required for each class of change. Ward enforcement is implemented in an authority process separate from the familiar — the familiar cannot opt out or work around it.
-
-See [`docs/ward-primer.md`](docs/ward-primer.md) for the full introduction.
-
----
-
-### Does my agent need to use OpenCoven to be compliant?
-
-No. OpenCoven is the research collective that developed this spec, but compliance requires nothing from OpenCoven's stack.
-
-You need:
-1. `SOUL.md`, `IDENTITY.md`, and `ward.toml` files satisfying the schemas in this repo
-2. A runtime that injects `SOUL.md` into the familiar's context at session start
-3. An enforcement mechanism for the Ward (your own implementation, conforming to the Ward spec)
-
-You can implement all of this independently. MIT license. No attribution required for compliance.
-
----
-
-### Can I extend the spec?
-
-Yes — additively. You can add new optional properties, define domain-specific role schemas, and create custom Ward tiers for your use case.
-
-What you cannot do: weaken the five properties. A familiar claiming familiar-contract compliance that does not satisfy Named Identity, Defined Purpose, Bounded Authority, Persistent Memory, and Human Belonging is not compliant. Extensions must be additive; they cannot subtract from the normative core.
-
-If you create a widely-used extension, consider contributing it as a proposal to this repo. See [`CONTRIBUTING.md`](.github/CONTRIBUTING.md).
-
----
-
-### What's the license?
-
-MIT. Use it, fork it, build on it, ship it. No strings. Attribution appreciated but not required.
-
----
-
-### What does "the self-improvement loop cannot touch the protected surface" mean in practice?
-
-It means: when your familiar generates a proposal to modify its own scaffolding (as in the Self-Harness architecture), the Ward daemon checks that proposal before it is applied. If the proposal targets any file in the protected surface — `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, `ward.toml`, the person binding — it is rejected automatically, regardless of how compelling the familiar's rationale sounds.
-
-The familiar cannot change who it is. It can change how it works. That distinction is the entire contract.
-
----
-
-### Is this related to the Voodoo Doll / Sympathetic Familiar Architecture?
-
-Familiar-contract is the identity layer. The Sympathetic Familiar Architecture (Doll architecture) is a delegation and sandboxing pattern built on top of it. You can implement familiar-contract without the Doll architecture.
-
-The Doll architecture is part of the OpenCoven Ward spec (v0.2+) and is not required for v0.1 compliance.
-
----
-
-### What if a familiar doesn't have a self-improvement loop?
-
-The protected surface still matters.
-
-Even without an active self-improvement loop, a familiar needs a protected surface because:
-1. Future model upgrades or fine-tuning may inadvertently drift identity
-2. Adversarial prompts may attempt to rewrite the familiar's stated purpose
-3. Administrators may accidentally overwrite `SOUL.md` during routine maintenance
-4. Compliance claims become auditable when there's a declared protected surface
-
-The Ward governs the self-improvement loop primarily, but it also protects against all of the above.
-
----
-
-### How does this relate to AI safety research?
-
-The Familiar Contract addresses a specific, narrow governance problem: what constraints govern a self-modifying agent's identity?
-
-It is not a general AI alignment framework. It does not address:
-- Value alignment at the model level
-- Reward hacking or deceptive alignment
-- Multi-agent coordination risks at scale
-- AGI safety
-
-What it does address: the operational gap between "the self-improvement loop works" and "the self-improvement loop is governed." That gap is real, current, and tractable. The Familiar Contract is a tractable answer to a tractable problem.
-
----
-
-### Where can I follow development?
-
-- This repo: [github.com/OpenCoven/familiar-contract](https://github.com/OpenCoven/familiar-contract)
-- OpenCoven Grimoire: [coven-grimoire.vercel.app](https://coven-grimoire.vercel.app) — where research notes and articles about the spec are published
-- OpenCoven GitHub org: [github.com/OpenCoven](https://github.com/OpenCoven)
+This root-level file is kept only so older links continue to resolve. It is intentionally non-normative; use [`docs/faq.md`](docs/faq.md) and [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) for current behavior.
diff --git a/PRIMER.md b/PRIMER.md
@@ -42,15 +42,17 @@ The Familiar Contract names the boundary. The Ward (the enforcement mechanism) i
 
 ## What you need to create a compliant familiar
 
-Three files:
+Four required files:
 
-**`SOUL.md`** — who the familiar is. Name, purpose, vibe, what it is not. This is the human-readable identity document. See [`schemas/soul.schema.json`](../schemas/soul.schema.json) for the required fields.
+**`SOUL.md`** — who the familiar is. Name, purpose, vibe, what it is not. This is the human-readable identity document. See [`schemas/soul.schema.json`](schemas/soul.schema.json) for the required fields.
 
 **`IDENTITY.md`** — the machine-readable identity record. Name, pronouns, creature type, Coven membership (if any), emoji. Minimal structured data that a validator can check.
 
-**`ward.toml`** — the governance document. Protected files, editable files, approval tiers. This is what tells the self-improvement loop what it cannot touch. See [`schemas/ward.schema.json`](../schemas/ward.schema.json).
+**`MEMORY.md`** — the familiar's persistent memory surface. It is required for structural conformance and must also appear on the Ward's protected surface.
 
-Start from [`examples/minimal/`](../examples/minimal/) — that's the floor. [`examples/sage/`](../examples/sage/) shows a full compliant familiar (Sage is a real familiar running on OpenCoven's infrastructure).
+**`ward.toml`** — the governance document. Protected files, editable files, approval tiers. This is what tells the self-improvement loop what it cannot touch. See [`schemas/ward.schema.json`](schemas/ward.schema.json).
+
+Start from [`examples/minimal/`](examples/minimal/) — that's the floor. [`examples/sage/`](examples/sage/) shows a richer structurally conformant familiar directory. Sage's runtime enforcement lives outside this repo fixture.
 
 ---
 
@@ -61,11 +63,11 @@ None in particular. The spec is runtime-portable by design.
 **Claude Code, Codex, Cursor, OpenHands** — all compatible. The spec operates at the identity and governance layer, not at the execution layer.
 
 What you need:
-- A way to store `SOUL.md`, `IDENTITY.md`, `ward.toml` as files accessible to the familiar
+- A way to store `SOUL.md`, `IDENTITY.md`, `MEMORY.md`, and `ward.toml` as files accessible to the familiar
 - A runtime that can inject `SOUL.md` content into the familiar's context at session start
 - An enforcement mechanism for the Ward (your own or based on the Ward spec)
 
-The validator in this repo checks schema compliance against the three required files. It does not require any specific runtime.
+The validator in this repo checks one claimant directory against the four required files. For a structural-conformance claim, pair that claimant-directory run with `bash tests/conformance/run-conformance.sh` from the same repository version. The validator checks your directory; the bundled conformance suite verifies that the reference validator accepts the positive fixtures and rejects the negative fixtures.
 
 ---
 
@@ -78,7 +80,7 @@ A Ward is a `ward.toml` file that declares:
 - Which files are editable (proposals allowed)
 - What approval is required for each class of change
 
-The Ward spec is published separately. See [`docs/ward-primer.md`](../docs/ward-primer.md) for the short version.
+The Ward spec is published separately. See [`docs/ward-primer.md`](docs/ward-primer.md) for the short version.
 
 ---
 
@@ -92,9 +94,10 @@ You do not need to use OpenCoven's infrastructure to implement familiar-contract
 
 ## Where to go next
 
-- [`SPEC.md`](../SPEC.md) — the normative specification
-- [`examples/minimal/`](../examples/minimal/) — the minimal compliant familiar (Lumen)
-- [`examples/sage/`](../examples/sage/) — a full compliant familiar (Sage)
-- `node validators/validate.js ./your-directory` — validate your familiar
-- [`FAQ.md`](../FAQ.md) — common questions
-- [`docs/comparison.md`](../docs/comparison.md) — how this relates to other approaches
+- [`rfcs/RFC-0001-familiar-contract.md`](rfcs/RFC-0001-familiar-contract.md) — the normative specification (v0.4.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
+- `bash tests/conformance/run-conformance.sh` — verify the bundled reference validator + fixtures for the same contract version
+- [`docs/faq.md`](docs/faq.md) — common questions
+- [`docs/comparison.md`](docs/comparison.md) — how this relates to other approaches