Skip to content

Establish Psyche roadmap and agent-readiness foundation #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
BunsDev wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Establish Psyche roadmap and agent-readiness foundation #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
# Psyche agent guide

This is the repository entrypoint for coding agents and human contributors. Keep it short and route detailed work to the canonical documents below.

## Mission

Psyche is the canonical orchestration protocol for OpenCoven. Preserve identity, authority, correlation, durability, and recovery across runtimes and surfaces.

Psyche Build is the first planned reference client; it is not the protocol owner. Coven, Threads, and Familiar Contract retain their own canonical domains.

## Start here

1. Read `README.md`.
2. Read `docs/ROADMAP.md` and confirm the work has an owning issue.
3. Read `docs/PROTOCOL-OWNERSHIP.md` before changing a cross-repository boundary.
4. Read the scoped architecture/testing documents relevant to the change.
5. Run `./scripts/agent-bootstrap`.
6. Run `./scripts/agent-check fast` before editing and after each bounded slice.
7. Run `./scripts/agent-check full` before requesting review.

## Canonical documents

- Architecture and dependency direction: `docs/ARCHITECTURE.md`
- Protocol/schema inventory: `docs/SCHEMAS.md`
- Deterministic evidence model: `docs/TESTING.md`
- Current G2 evidence: `docs/G2-EVIDENCE.md`
- CLI boundary: `docs/CLI.md`
- Configuration: `docs/CONFIGURATION.md`
- Program roadmap: `docs/ROADMAP.md`
- Cross-repository ownership: `docs/PROTOCOL-OWNERSHIP.md`
- Contribution and review contract: `CONTRIBUTING.md`
- Security reporting and protected data: `SECURITY.md`
- Machine-readable repository contract: `agent/manifest.yaml`

## Ownership by path

| Path | Canonical responsibility |
|---|---|
| `crates/psyche-core/**` | IDs, records, validation, canonicalization, digests, errors |
| `crates/psyche-store/**` | durable storage, transitions, migrations, quarantine, retention |
| `crates/psyche-coven/**` | typed Coven adapter; never replaces core decisions |
| `crates/psyche-surfaces/**` | bounded surface ports |
| `crates/psyche-runtime/**` | runtime composition and shutdown |
| `crates/psyche-cli/**` | process/CLI boundary |
| `crates/psyche-test-support/**` | reusable conformance evidence, not production authority |
| `packages/psyche-npm/**` | npm wrapper and packed distribution |
| `.github/**`, `scripts/**` | CI, evidence, release, and verification controls |

## Risk classes

- **R0:** prose and examples with no contract claim.
- **R1:** pure implementation that cannot mutate durable state or authority.
- **R2:** local mutable state, migrations, or recovery helpers.
- **R3:** network, credentials, external systems, or user data.
- **R4:** canonical identity, authorization, persistence, dispatch, receipts, cancellation, recovery, evidence, and release.

Psyche is an R4 repository. Any R2–R4 change needs explicit failure, rollback, and retained-evidence criteria. Do not widen authority to simplify a test.

## Invariants

Never:

- derive durable identity from a tracker, process, tmux pane, path, transport, UI component, or provider session;
- treat successful decoding or dispatch as authorized completion;
- replace an unknown or ambiguous result with success;
- redispatch an indeterminate effect without the canonical reconciliation/fence rule;
- mutate append-only records or rewrite history to “repair” state;
- accept unknown major versions, enums, kinds, or widened capabilities silently;
- hand-edit generated fixtures or evidence where a canonical generator exists;
- weaken negative, crash, restart, quarantine, or structured-denial tests;
- expose secrets or unrestricted user/project content in evidence.

## Change workflow

1. Claim one issue and one bounded outcome.
2. Record current behavior and the invariant being preserved.
3. Add or identify focused positive and negative tests.
4. Implement the smallest compatible slice.
5. Run the fast gate.
6. Run the relevant conformance, migration, property, or crash tests.
7. Run the full gate.
8. Inspect `git diff --check` and ensure generated outputs are canonical.
9. Open a focused PR with exact commands/results, risk, migration, rollback, affected consumers, and remaining proof gaps.
10. Do not close the outcome until durable evidence is linked.

## Protected surfaces

Treat these as requiring focused owner review:

- canonical ID prefixes and record schemas;
- canonical JSON and digest construction;
- structured error/denial vocabulary;
- migrations and persisted compatibility;
- adoption, dispatch, fencing, cancellation, receipts, and recovery;
- quarantine and retention;
- runtime shutdown/checkpoint ordering;
- conformance fixtures and evidence checker allowlists;
- CI, supply-chain, secret, and release controls.

## Generated and evidence files

Do not edit generated artifacts manually. Use the documented generator or update the generator and artifact in the same PR.

`docs/G2-EVIDENCE.md` is retained evidence tied to immutable commits and runs. It is not a mutable status dashboard. New evidence must identify source SHA, command, result, and immutable artifact/run.

## Verification

```sh
./scripts/agent-check fast
./scripts/agent-check full
```

The full local script intentionally does not replace GitHub's cross-platform, cargo-deny, or full-history secret jobs. A local pass is necessary, not sufficient.

## Cross-repository changes

Before changing a public contract:

- update the producer/consumer ownership map;
- identify every affected OpenCoven repository;
- define version negotiation and rollback;
- update immutable compatibility pins/canaries;
- preserve old reads until migration evidence permits removal;
- do not make Psyche Build, Cave, Coven, or Threads a hidden source of canonical truth.

## Completion evidence

A completion comment or PR must include:

- objective and non-goals;
- files intentionally changed;
- risk class and protected surfaces touched;
- exact tests and results;
- compatibility and consumer impact;
- migration and rollback;
- generated artifact provenance;
- unresolved uncertainty or unavailable platform evidence;
- exact commit SHA.
93 changes: 93 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Contributing to Psyche

Psyche is a protocol and durable-state repository. Contributions are welcome, but compatibility and failure behavior matter as much as the happy path.

## Before starting

1. Read `README.md`, `AGENTS.md`, and `docs/ROADMAP.md`.
2. Find or open one owning issue with outcome, acceptance criteria, dependencies, non-goals, and evidence requirements.
3. For cross-repository work, read `docs/PROTOCOL-OWNERSHIP.md`.
4. Classify the change using the risk classes in `AGENTS.md`.

Do not begin an R3/R4 contract change from an unreviewed implementation assumption.

## Setup

```sh
git clone https://github.com/OpenCoven/psyche.git
cd psyche
./scripts/agent-bootstrap
./scripts/agent-check fast
```

The pinned Rust version is declared in `rust-toolchain.toml`. Use the locked Cargo dependency graph.

## Development loop

Keep each pull request focused on one contract or capability boundary.

```sh
./scripts/agent-check fast
# make a bounded change
./scripts/agent-check fast
# run the directly affected conformance/migration/fault tests
./scripts/agent-check full
```

Add behavior-level tests before changing canonical records, transitions, persistence, dispatch, or recovery.

## Pull request contract

A pull request should include:

- the owning issue;
- objective and non-goals;
- current behavior and invariant;
- risk class;
- public records, schemas, migrations, or consumers affected;
- exact commands and results;
- negative, crash, restart, ambiguity, and downgrade coverage where relevant;
- generated artifacts and generator command;
- migration and rollback;
- security/privacy impact;
- remaining proof gaps;
- exact final head SHA.

A merged source diff is not enough to close a runtime or compatibility outcome. Link retained evidence.

## Compatibility

Do not:

- change a stable record or ID without versioning;
- accept unknown versions/enums by guessing;
- silently widen capabilities;
- reuse process/UI/provider identifiers as protocol IDs;
- remove compatibility reads before migration evidence exists;
- convert ambiguous or indeterminate effects into success;
- modify golden bytes without an explicit compatibility decision.

Cross-repository changes must identify producers, consumers, release order, immutable canary pins, and rollback.

## Generated files

Use canonical generators. Never hand-edit generated schemas, fixtures, packed artifacts, or evidence summaries to make a check pass.

After generation:

```sh
git diff --check
git status --short
```

Review every generated change.

## Security and protected data

Follow `SECURITY.md`. Public issues, PRs, fixtures, and evidence must not contain secrets, credentials, private keys, raw prompts, unrestricted terminal output, private repository contents, full environment dumps, infrastructure details, or unnecessary personal paths.

## Review

R2–R4 changes require review from the owner of the affected surface. Resolve every current review finding and rerun required checks on the exact final head.

Keep changes reversible until compatibility and runtime evidence is complete.
21 changes: 21 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 OpenCoven contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
114 changes: 114 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Psyche

Psyche is OpenCoven's canonical orchestration protocol and reference implementation for durable, identity-preserving agent work.

It defines how tasks, graphs, lanes, execution attempts, delegations, deliveries, approvals, receipts, cancellation, recovery, and terminal outcomes are represented and verified without coupling those identities to a UI, tracker, process, transport, or persistence provider.

> **Status:** pre-1.0 protocol foundation. The current repository has passed the documented G2 contract-foundation evidence. Consumer-ready protocol v1 artifacts and the first Psyche Build compatibility canary are tracked on the active roadmap. Do not infer support beyond retained evidence.

## Canonical ownership

Psyche owns:

- orchestration identity and correlation;
- task, graph, lane, attempt, delegation, and delivery contracts;
- canonical serialization, digests, structured denials, and compatibility behavior;
- capability/lease, approval, receipt, cancellation, recovery, and terminal-state semantics;
- adapter conformance requirements.

Psyche does not own:

- familiar or person-binding identity (`OpenCoven/familiar-contract`);
- protected-surface authorization decisions (`OpenCoven/coven-threads`);
- daemon session, persistence, or runtime authority (`OpenCoven/coven`);
- product UI, tmux panes, worktrees, branches, provider sessions, or tracker state;
- the Psyche Build product (`OpenCoven/psyche-build`).

See [Protocol ownership](docs/PROTOCOL-OWNERSHIP.md) for the proposed cross-repository boundary and [the roadmap](docs/ROADMAP.md) for graduation gates.

## Repository map

| Path | Responsibility |
|---|---|
| `crates/psyche-core` | Canonical contracts, IDs, validation, digests, schemas, and errors |
| `crates/psyche-store` | Durable records, append-only transitions, migrations, quarantine, and retention |
| `crates/psyche-coven` | Typed Coven adapter boundary |
| `crates/psyche-surfaces` | Bounded surface ports |
| `crates/psyche-runtime` | Runtime composition and lifecycle |
| `crates/psyche-cli` | CLI and daemon process boundary |
| `crates/psyche-config` | Configuration loading and validation |
| `crates/psyche-test-support` | Reusable adapter conformance, property, fault, and restart evidence |
| `packages/psyche-npm` | Dependency-free npm distribution wrapper |
| `docs` | Architecture, schemas, testing, evidence, ownership, and roadmap |
| `scripts` | Evidence and repository verification tools |

The dependency direction and crate ownership are documented in [Architecture](docs/ARCHITECTURE.md).

## Requirements

- Rust **1.88.0**, pinned by `rust-toolchain.toml`
- Cargo with the locked dependency graph
- Python 3 for evidence verification
- Node.js 20+ and npm for the distribution wrapper checks
- Git
- A POSIX shell for the repository helper scripts

The GitHub workflow remains the source of truth for the full Linux, macOS, Windows, supply-chain, secret, and npm matrix.

## Quick start

```sh
./scripts/agent-bootstrap
./scripts/agent-check fast
```

Run the complete local gate before requesting review:

```sh
./scripts/agent-check full
```

Direct Cargo entrypoints remain available:

```sh
cargo test --workspace --locked
cargo test -p psyche-test-support --test conformance
cargo run -p psyche-cli -- --help
```

See [CLI](docs/CLI.md), [Configuration](docs/CONFIGURATION.md), and [Testing](docs/TESTING.md).

## Change policy

Psyche is an R4 repository: small mistakes can fork identity, widen authority, lose durable evidence, or make an ambiguous effect appear complete.

Changes to canonical IDs, record shapes, digests, migrations, dispatch, persistence, cancellation, recovery, compatibility, or release evidence require:

1. an owning roadmap issue;
2. explicit positive and negative acceptance criteria;
3. migration and rollback analysis;
4. focused contract tests before implementation;
5. exact-head CI evidence;
6. affected-consumer and compatibility-canary review.

Read [AGENTS.md](AGENTS.md) before making changes and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Roadmap

The active 90-day program is tracked in:

- [Roadmap document](docs/ROADMAP.md)
- [Roadmap control issue](https://github.com/OpenCoven/psyche/issues/9)
- [Repository and agent-readiness foundation](https://github.com/OpenCoven/psyche/issues/10)
- [Protocol v1 publication](https://github.com/OpenCoven/psyche/issues/11)
- [Cross-repository ownership](https://github.com/OpenCoven/psyche/issues/12)
- [Psyche Build reference-client canary](https://github.com/OpenCoven/psyche/issues/13)
- [Security, release, support, and governance](https://github.com/OpenCoven/psyche/issues/14)

## Security

Do not post credentials, private keys, raw prompts, unrestricted terminal output, private repository contents, environment dumps, or sensitive paths in public issues or retained evidence. Follow [SECURITY.md](SECURITY.md).

## License

MIT. See [LICENSE](LICENSE).
Loading
Loading