Contract Catalog

This directory is the only normative specification for current, testable joplin-md-sync behavior. Runtime modules, user guides, and maintainer notes link here instead of restating requirements. User procedures start in the Overview, design rationale and change procedures start in Architecture, and unpublished build inputs live under docs/site/.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are interpreted as described by BCP 14 when they appear in uppercase. Every normative assertion has a permanent ID and links to one or more automated tests. This is a repository-scale requirements verification matrix following NASA guidance on requirements traceability and verification.

Contract Format

Every assertion uses this shape:

### `ABC-NNN` - Short title

**Contract:** The implementation MUST ...

**Evidence:**

- [linked test name] - `tests/path.py::TestClass::test_behavior`

IDs are permanent. Changing or removing an assertion requires reviewing its evidence and every implementation, user, and maintenance reference. External specifications may explain a requirement but never replace repository test evidence. A successful supported Make test run is the execution record.

Index

Contract	Prefix	Scope
CLI and output	CLI	Commands, JSON envelope, exit codes, connection resolution, and read-only inspection
Workspace	WSP	Managed Markdown, notebook identity, paths, and local state layout
Synchronization	SYN	Three-way planning, deletes, conflicts, concurrency, journals, and recovery
Agent interfaces	AIF	Shared tool registry, MCP, GPT Actions, OpenAPI, limits, and failure behavior
Service	SVC	Headless installation, credentials, systemd lifecycle, upgrades, and removal
Security	SEC	Token, network, filesystem, content, and destructive-operation boundaries
Dependencies	DEP	Direct manifests, hash locks, platform audiences, audit, and submission
CI and releases	CIR	Workflow topology, permissions, Pages, versions, and publication