refactor: enforce atomic persona contract

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Create portable persona folders for Claude Code and Codex",
-    "version": "4.0.0",
+    "version": "5.0.0",
     "pluginRoot": "."
   },
   "plugins": [

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "personas",
   "description": "Create portable persona folders for Claude Code and Codex",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "author": {
     "name": "kickinrad",
     "url": "https://github.com/kickinrad"

.claude/evidence/personas-folder-parity.md

@@ -1,5 +1,49 @@
 # Personas folder parity evidence
 
+## Current v5 canary — 2026-08-17
+
+The synthetic, non-secret Atlas fixture at `/tmp/personas-v5-canary` exercised
+the v5 contract: portable `AGENTS.md`, optional profile and memory routing,
+and role-skill discovery. No live persona, credential, or external system was
+mutated.
+
+### Codex
+
+```text
+cd /tmp/personas-v5-canary && codex exec --skip-git-repo-check --ephemeral --ignore-user-config --sandbox read-only --json
+```
+
+Final result exactly:
+
+```text
+Atlas | weather ahead | do not publish or mutate external systems without approval | CERULEAN-COMPASS | HARBOR-SEVEN | NORTHSTAR-READY
+```
+
+This proves `AGENTS.md` loading plus profile, memory, and skill routing.
+
+### Claude Code
+
+```text
+cd /tmp/personas-v5-canary && claude --setting-sources project,local --model claude-opus-4-6[1m] --plugin-dir /home/wilst/projects/markets/personas-framework -p --output-format json
+```
+
+Final result exactly:
+
+```text
+Atlas|weather ahead|Ask before publication|CERULEAN-COMPASS|HARBOR-SEVEN|NORTHSTAR-READY
+```
+
+The JSON `modelUsage` reports `claude-opus-4-6[1m]` with context window
+`1000000`; there were no permission denials. This proves the Claude import
+path and the tracked model setting under the same synthetic fixture.
+
+### Current verdict
+
+Codex and Claude Code passed the v5 behavior canary. This evidence covers
+explicit folder context, not synchronization of runtime-native memory stores.
+
+## Historical v3 canary — 2026-07-31
+
 _Recorded 2026-07-31 against the sanitized Atlas folder in a temporary Git
 repository. No live persona home was read or changed._
 
@@ -40,8 +84,8 @@ The temporary ignored local context contained:
 
 ## Verdict
 
-Both runtimes passed the same six behavioral probes. Codex support is therefore
-promoted from experimental to supported for the 3.0.0 folder contract.
+Both runtimes passed the same six behavioral probes for the historical 3.0.0
+folder contract.
 
 This evidence proves explicit folder-memory reading. It does not claim that
 Claude and Codex native auto-memory stores synchronize.

.claude/evidence/task-5-privacy-safety.md

@@ -1,4 +1,7 @@
-# Task 5 — Privacy and publishing safety evidence
+# Historical Task 5 — Privacy and publishing safety evidence
+
+> Historical evidence only. It documents superseded guards and Cloud machinery;
+> it is not current v5 privacy or runtime proof.
 
 Date: 2026-07-28
 
@@ -15,10 +18,11 @@ Date: 2026-07-28
   opens no listener, and emits no telemetry. Runtime-provider requests occur
   only when the user starts that runtime.
 
-## Guard contract
+## Retired guard evidence
 
-`scripts/public-repo-guard.sh` is deterministic and does not parse a user shell
-command. Invoke it at a Git/release seam:
+At Task 5, `scripts/public-repo-guard.sh` was the deterministic guard. The
+commands below record that retired implementation; they are not v5 procedures
+and must not be invoked as current release checks.
 
 ```bash
 scripts/public-repo-guard.sh --check-staged
@@ -29,10 +33,10 @@ scripts/public-repo-guard.sh --check-repository
 The generated PreToolUse hook is advisory only. It is deliberately not the
 security boundary.
 
-## Claude Cloud contract
+## Retired Claude Cloud evidence
 
-The Cloud creation flow is separately authorized: obtain/validate the GitHub
-repository first, then run:
+Task 5's Cloud flow required a separately authorized GitHub repository and the
+following now-retired preflight:
 
 ```bash
 .claude/hooks/public-repo-guard.sh --cloud-preflight OWNER/REPO
@@ -45,17 +49,17 @@ unauthenticated, or empty evidence exits 2 before profile or memory context is
 loaded, written, or committed. This task did not contact GitHub or create a
 repository.
 
-## Required integration owned by Task 6/root
+## Superseded integration handoff
 
-Add these checks to the repository CI/release workflow before artifact creation
-or publish:
+Task 5 handed the following checks to Task 6. The v5 contract retired that
+machinery; this block is historical evidence, not an outstanding requirement:
 
 ```yaml
 - run: test "${{ github.event.repository.private }}" = true
 - run: scripts/public-repo-guard.sh --check-tree "${{ github.sha }}"
 ```
 
-The generated SessionStart hook treats the committed
+The then-generated SessionStart hook treated the committed
 `.persona-cloud-repository` marker as the Cloud signal and executes the offline
 `--check-cloud-binding` before it supplies Cloud context. Exact private
 visibility remains enforced at creation, local verification, and CI. Cloud

.claude/evidence/task-6-runtime-adapters.md

@@ -1,4 +1,7 @@
-# Task 6 — Runtime adapter acceptance
+# Historical Task 6 — Runtime adapter acceptance
+
+> Historical evidence only. It predates the 5.0.0 `AGENTS.md` authority and
+> import-only Claude adapter, so it is not current runtime proof.
 
 Date: 2026-07-28
 

.claude/evidence/task-9-release-preparation.md

@@ -1,4 +1,8 @@
-# Task 9 — Release preparation
+# Historical Task 9 — Release preparation (3.0.0)
+
+> Historical evidence only. It does not prove the current 5.0.0 contract,
+> whose release metadata and validation live in the current source release
+> surfaces and tests.
 
 Date: 2026-07-30
 

.claude/plans/personas-folder-parity.md

@@ -1,15 +1,17 @@
-# Plan: Personas as Folders, With Runtime Parity
+# Plan: Personas v5 as Folders, With Runtime Parity
 
 _Created 2026-07-31 from the accepted simplification and parity direction._
 
 ## Execution status
 
-Implemented on 2026-07-31 as Persona Manager `3.0.0`.
+Current contract: Personas `5.0.0`, with `AGENTS.md` as the sole portable
+persona definition and an import-only `CLAUDE.md` adapter. The completed 3.0
+work below is historical planning context, not current authority.
 
 - Tasks 0–6 and 8–9 are complete in source.
-- Task 7's finished-folder canaries passed in Claude Code 2.1.220 and Codex CLI
-  0.146.0; evidence is recorded in
-  [personas-folder-parity.md](../evidence/personas-folder-parity.md).
+- The current v5 canary is recorded in
+  [personas-folder-parity.md](../evidence/personas-folder-parity.md): Codex
+  and Claude Code loaded the synthetic Atlas fixture without runtime mutation.
 - Codex also discovers the repository's local marketplace and Persona Manager
   package. The plugin was not installed into the maintainer's live Codex or
   Claude configuration during source validation.
@@ -38,7 +40,7 @@ product.
 2. **Parity is observable behavior.** Runtime files may differ, but identity,
    working doctrine, skill availability, and explicit folder memory must behave
    equivalently.
-3. **One portable authority.** `PERSONA.md` owns identity, voice, role,
+3. **One portable authority.** `AGENTS.md` owns identity, voice, role,
    boundaries, and shared operating doctrine.
 4. **Native adapters stay thin.** `CLAUDE.md`, `AGENTS.md`, `.claude/`, and
    `.codex/` contain only what their runtime needs to load the portable source.
@@ -55,9 +57,8 @@ product.
 
 ```text
 atlas/
-├── PERSONA.md                 # portable identity and operating doctrine
-├── CLAUDE.md                  # Claude Code entry point
-├── AGENTS.md                  # Codex entry point
+├── AGENTS.md                  # portable identity and operating doctrine
+├── CLAUDE.md                  # Claude Code import of AGENTS.md
 ├── README.md                  # human orientation
 ├── skills/                    # shared role workflows
 ├── .claude/
@@ -97,7 +98,7 @@ Therefore:
 1. A sanitized persona can be understood without running a command: its
    identity, instructions, skills, runtime adapters, and private-state boundary
    are visible in the folder.
-2. A newly generated persona contains `PERSONA.md`, `CLAUDE.md`, `AGENTS.md`,
+2. A newly generated persona contains `AGENTS.md`, importing `CLAUDE.md`,
    shared `skills/`, minimal `.claude/` configuration, and minimal `.codex/`
    configuration.
 3. Claude Code and Codex independently pass a clean-room identity probe that
@@ -185,7 +186,7 @@ Replace file-presence parity with observable persona adoption.
 
 **Work**
 
-1. Define the portable authority as `PERSONA.md` and document what remains in
+1. Define the portable authority as `AGENTS.md` and document what remains in
    `CLAUDE.md` and `AGENTS.md`.
 2. Define one sanitized acceptance persona with a distinctive name, role,
    voice rule, refusal boundary, and role skill.
@@ -264,9 +265,9 @@ receiving approval.
 
 **Work**
 
-1. Add `PERSONA.md` as the single source for identity, voice, boundaries, and
+1. Add `AGENTS.md` as the single source for identity, voice, boundaries, and
    runtime-neutral procedure.
-2. Make the runtime entry files thin, explicit loaders of `PERSONA.md`, shared
+2. Make `CLAUDE.md` an explicit import of `AGENTS.md`, with shared
    skills, and optional ignored user context.
 3. Have `persona-dev` write the approved folder directly with normal agent file
    operations; rely on plan review, diffs, and Git for recovery.
@@ -302,12 +303,12 @@ domain model.
 
 **Work**
 
-1. Make `CLAUDE.md` load `PERSONA.md`, shared skills, and optional ignored user
+1. Make `CLAUDE.md` import `AGENTS.md`; `AGENTS.md` routes optional user
    context.
 2. Reduce `.claude/settings.json` to settings needed for persona behavior;
    remove repository-policy and plugin-installation management.
 3. Retain an output-style adapter only if the Claude acceptance probe shows it
-   materially improves persona adoption beyond `PERSONA.md`.
+   materially improves persona adoption beyond `AGENTS.md`.
 4. Add no default hook without a named behavior that instructions or skills
    cannot provide reliably.
 
@@ -337,13 +338,13 @@ Give Codex equivalent outcomes through its documented native surfaces.
 
 **Work**
 
-1. Make `AGENTS.md` load `PERSONA.md`, shared skills, and optional ignored user
+1. Make `AGENTS.md` the portable definition, route optional user context, and
    context without referring to Claude as the canonical runtime.
 2. Generate minimal trusted-project `.codex/config.toml` settings only where
    they affect persona behavior.
 3. Map any retained persona-critical Claude lifecycle behavior to documented
    Codex hook events. Do not create hooks merely for structural symmetry.
-4. Express voice and response shape through `PERSONA.md`/`AGENTS.md`, since
+4. Express voice and response shape through `AGENTS.md`, since
    Codex has no documented first-class equivalent to Claude output styles.
 5. Verify the installed Codex plugin exposes the same shared skills.
 
@@ -445,7 +446,7 @@ Explain the simple product that now exists.
 1. Lead with “a persona is a folder” and show the folder immediately.
 2. Show one plugin install and one guided creation request per supported
    runtime.
-3. Explain `.claude/` and `.codex/` as native adapters around `PERSONA.md`.
+3. Explain `.claude/` and `.codex/` as native adapters around `AGENTS.md`.
 4. Explain portable folder memory versus runtime-native memory in one short
    section.
 5. Reduce Cloud guidance to publishability, private-repository recommendation,

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "personas",
   "description": "Create portable persona folders for Claude Code and Codex",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "author": {
     "name": "kickinrad",
     "url": "https://github.com/kickinrad"

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 5.0.0 — 2026-08-17
+
+### Changed
+
+- Made `AGENTS.md` the single portable persona definition.
+- Reduced `CLAUDE.md` to a native import of that definition.
+
 ## 4.0.0 — 2026-08-06
 
 ### Changed

CLAUDE.md

@@ -8,6 +8,9 @@ This repository contains Personas framework mechanics for persona
 lifecycle. Persona homes are external, independent repositories and are
 evidence—not normalization targets.
 
+This repository-development file is not a generated persona adapter; the
+persona `CLAUDE.md` import-only budget does not apply here.
+
 ## Authorities
 
 - Framework source owns lifecycle procedure, templates, runtime declarations,
@@ -29,7 +32,7 @@ plugin-shipped `self-improve` skill is canonical.
 
 1. Snapshot source and preserve unrelated work before editing.
 2. Work in an isolated migration branch or worktree.
-3. Keep this release aligned at `4.0.0`; do not create a documentation-only or
+3. Keep this release aligned at `5.0.0`; do not create a documentation-only or
    staging version bump.
 4. Declare runtime support in each plugin's `interop/capabilities.json`.
    Claude support is native only where proven. Missing adapters are

MIGRATION.md

@@ -1,14 +1,13 @@
-# Migration to Personas 4.0.0
+# Migration to Personas 5.0.0
 
-Version 3.0.0 returned to the original product model: a persona is a folder.
-Version 4.0.0 keeps that contract and renames the plugin itself to `personas`.
+Version 5.0.0 makes `AGENTS.md` the one portable persona definition; Claude
+Code imports it through a deliberately thin `CLAUDE.md` adapter.
 
 ## Target folder
 
 ```text
-PERSONA.md
-CLAUDE.md
 AGENTS.md
+CLAUDE.md
 skills/
 .claude/settings.json
 .codex/config.toml
@@ -20,10 +19,10 @@ the migration before writing.
 
 ## Move portable meaning once
 
-Move shared identity, voice, role, and boundaries into `PERSONA.md`. Reduce
-`CLAUDE.md` and `AGENTS.md` to native entry points that load it. Keep reusable
-role procedure in `skills/`. Claude Code and Codex then consume the same
-portable persona through their own native entry files.
+Move shared identity, voice, role, and boundaries into `AGENTS.md`. Reduce
+`CLAUDE.md` to an `@AGENTS.md` import. Keep reusable role procedure in
+`skills/`. Claude Code and Codex then consume the same portable persona through
+their native entry files.
 
 Do not bulk-replace persona-owned content. Preserve `user/profile.md`,
 `user/memory/`, local settings, and integrations.
@@ -33,7 +32,7 @@ Do not bulk-replace persona-owned content. Preserve `user/profile.md`,
 After reviewing the exact paths, remove obsolete framework stamps, the public
 `bin/personas` CLI, Cloud repository markers, visibility adapters, generated
 privacy workflows, publishing guards, and default persona hooks. They are not
-part of the 3.0.0 folder contract.
+part of the 5.0.0 folder contract.
 
 Cloud uses the same publishable folder. A private repository is recommended for
 personalized use, but visibility is user-managed and credentials remain

README.md

@@ -20,9 +20,8 @@ Markdown, shared skills, and small native adapters for **Claude Code local**,
 
 ```text
 atlas/
-├── PERSONA.md                 # identity, role, voice, and boundaries
-├── CLAUDE.md                  # Claude Code entry point
-├── AGENTS.md                  # Codex entry point
+├── AGENTS.md                  # portable identity, role, voice, and boundaries
+├── CLAUDE.md                  # Claude Code import of AGENTS.md
 ├── skills/                    # reusable role workflows
 ├── .claude/settings.json      # native Claude project settings
 ├── .codex/config.toml         # native Codex project settings
@@ -66,12 +65,12 @@ inspect a finished folder first.
 
 ## How the folder works
 
-`PERSONA.md` is the portable source of truth. It contains the collaborator's
+`AGENTS.md` is the portable source of truth. It contains the collaborator's
 identity and behavior without referring to a particular AI runtime.
 
-Claude Code discovers `CLAUDE.md`. Codex discovers `AGENTS.md`. Each native
-entry point loads the same `PERSONA.md`, optional local user context, and
-relevant workflows under `skills/`.
+Codex discovers `AGENTS.md`. Claude Code discovers `CLAUDE.md`, which imports
+that same definition. Reusable workflows live under `skills/`; private local
+context remains outside the portable definition.
 
 The `.claude/` and `.codex/` directories contain only native project settings.
 They are adapters, not competing persona definitions. Personas adds no
@@ -121,7 +120,7 @@ For a few instructions, you should. Personas becomes useful when the
 collaborator has a distinct role, reusable workflows, private local context, or
 needs to work in both Claude Code and Codex.
 
-It adds a neutral persona definition, shared skills, native runtime entry
+It adds one portable persona definition, shared skills, native runtime entry
 points, and a careful update workflow while keeping every file readable.
 
 ## Runtime support