Land Psyche repository and agent-readiness foundation

[BunsDev]

Outcome

Land the minimum repository and agent-readiness foundation required for a human or coding agent to understand, change, verify, and hand off Psyche from a clean checkout without private maintainer context.

Parent roadmap: #9
Priority: P0
Target phase: Phase 0 — Aug 26–Sep 8, 2026
Accountable owner: @BunsDev

Scope

• Add a root README.md that states status, canonical ownership, non-goals, architecture, quick start, verification, and roadmap.
• Add a concise root AGENTS.md that routes work by risk and directory rather than duplicating implementation documentation.
• Add agent/manifest.yaml describing repository role, canonical domains, risk class, protected/generated paths, verification commands, and produced/consumed contracts.
• Add scripts/agent-bootstrap for deterministic toolchain and clean-checkout preparation.
• Add scripts/agent-check fast|full as the one repository verification interface.
• Add CONTRIBUTING.md, SECURITY.md, and the repository LICENSE.
• Publish an active roadmap and protocol-ownership map.
• Add CI or contract checks that prevent the readiness surfaces from silently drifting.
• Verify commands from a clean Linux, macOS, and Windows checkout where the command is claimed cross-platform.

Risk and authority

This work may document existing protocol ownership, but it must not invent or widen protocol authority. Changes to canonical IDs, digests, structured errors, migrations, persistence, dispatch, cancellation, or recovery remain R4 and require focused contract review.

Protected surfaces include:

• crates/psyche-core/**
• crates/psyche-store/**
• crates/psyche-coven/**
• migrations and golden fixtures
• CI, release, and evidence verification
• protocol schema and compatibility documents

Acceptance criteria

• README.md, AGENTS.md, CONTRIBUTING.md, SECURITY.md, LICENSE, docs/ROADMAP.md, and agent/manifest.yaml exist and agree.
• ./scripts/agent-bootstrap succeeds from a supported clean checkout.
• ./scripts/agent-check fast completes the bounded developer gate.
• ./scripts/agent-check full delegates to the complete documented local gate and leaves the worktree clean.
• Existing CI remains the stronger source of truth for cross-platform, supply-chain, secret, and G2 evidence checks.
• A new contributor can identify canonical owners, prohibited shortcuts, generated files, supported commands, and the active roadmap without reading issue history.
• Temporary or historical G2 evidence is linked as evidence, not presented as the entire forward roadmap.
• The first implementation PR links exact CI results and any platform-specific proof gaps.

Non-goals

• Redesigning protocol records.
• Publishing protocol v1 artifacts.
• Implementing Psyche Build integration.
• Weakening existing G2 evidence checks.
• Turning AGENTS.md into a long-lived incident log.

Evidence

Link the focused readiness PR, clean-checkout commands, CI runs, review resolution, and merged commit here.

[BunsDev]

Initial implementation opened

Draft PR #15 implements the first bounded slice of this outcome at head 8a4ff6d2a9b8a659a7f4c343e9d9dacdb37ce263.

Included:

• README.md, AGENTS.md, CONTRIBUTING.md, SECURITY.md, and LICENSE;
• docs/ROADMAP.md and docs/PROTOCOL-OWNERSHIP.md;
• agent/manifest.yaml;
• executable scripts/agent-bootstrap and scripts/agent-check fast|full.

Pre-push validation covered shell syntax, YAML parsing/required keys, and a one-commit/ten-file GitHub compare with zero base divergence. The issue remains open pending exact-head CI, clean-checkout bootstrap/check execution, wording review, and merge evidence. No protocol records, migrations, dispatch, cancellation, or recovery behavior changed.