[RFC] AAMS is not a Spec - it is an Agent Contract

[ogerly]

Summary

AAMS calls itself a Specification (_spec: AAMS-MINI/1.0), but empirical analysis of 4 repositories shows it is not.

What AAMS actually defines

Element	Spec or Contract?
workspace.structure - folder definition	Spec
documentation_model - naming rules	Spec
agent_contract.on_first_entry - behavioral directive	Contract
agent_contract.on_session_start - behavioral directive	Contract
agent_contract.on_session_end - behavioral directive	Contract
bootstrap_rules - execution logic	Contract
secrets_policy - policy enforcement	Contract

A Specification defines what. A Contract defines what + how + when + what happens on deviation. AAMS defines all four.

Proposed reframing

AAMS is a machine-readable behavioral contract between an agent and a repository. Framework-independent. Drop-in for any repo.

Concrete changes proposed

• _spec key -> _contract key in .agent.json
• README: 'Specification' -> 'Agent Contract System'
• External description: 'Standard for agentic programming' -> 'Behavioral contract for agent-based work'

What does NOT change

• .agent.json as drop-in file
• Folder structure (WORKING/, Workpapers, Whitepapers, etc.)
• Framework independence, CC0 license, backward compatibility

Why this matters

The 'Manifest' in the name already carries this: a manifest is a declaration of intent with binding force - not a schema. This reframing also unblocks the WORKSPACE container issue (see related issue) - a Contract can specify discovery logic and conflict resolution behavior; a Spec cannot.

---

Field-tested on Mantis-Family workspace (4 repos, 2026-04-12) @ogerly / DEVmatrose