contract

type Boundary struct {
	// Name is a short, stable identifier for this boundary.
	Name string `yaml:"name"`
	// Description explains what the boundary protects and why.
	Description string `yaml:"description,omitempty"`
	// Paths lists the repository paths this boundary applies to.
	Paths []string `yaml:"paths,omitempty"`
	// Rule is a short, human-readable statement of how the boundary is
	// enforced (e.g. a script or CI check name).
	Rule string `yaml:"rule,omitempty"`
}

type CheckDecl struct {
	// Name is a short, stable identifier for this check (e.g. "lint").
	Name string `yaml:"name"`
	// Command is the shell command line that performs this check.
	Command string `yaml:"command"`
	// Reason explains why this check was selected or is required.
	Reason string `yaml:"reason,omitempty"`
	// RequiredTool names a binary this check depends on (e.g.
	// "golangci-lint"), or "" if it has no such dependency.
	RequiredTool string `yaml:"required_tool,omitempty"`
	// Networked marks a check that performs network I/O.
	Networked bool `yaml:"networked,omitempty"`
}

type CommandDecl struct {
	// Name is a short, stable identifier for this command (e.g.
	// "go-test").
	Name string `yaml:"name"`
	// Command is the shell command line a consumer would run (e.g.
	// "go test ./...").
	Command string `yaml:"command"`
	// Class classifies this command's impact. Validate rejects any value
	// that is not one of provenance.ClassSafe, ClassMutating,
	// ClassNetworked, ClassDestructive, or ClassApprovalRequired.
	Class provenance.CommandClass `yaml:"class"`
	// Reason explains why this command was classified the way it was.
	Reason string `yaml:"reason,omitempty"`
}

type Contract struct {
	// SchemaVersion identifies the version of this schema the document
	// was written against (see the package-level SchemaVersion constant).
	SchemaVersion string `yaml:"schema_version"`
	// Projects lists every project this contract covers. A contract
	// describing zero projects is rejected by Validate as meaningless.
	Projects []Project `yaml:"projects"`
	// Instructions declares applicable agent-instruction files and their
	// precedence.
	Instructions InstructionPrecedence `yaml:"instructions,omitempty"`
	// Boundaries lists lifecycle/module boundaries this repository
	// enforces.
	Boundaries []Boundary `yaml:"boundaries,omitempty"`
	// Commands lists commands this repository's agents may run,
	// classified by impact.
	Commands []CommandDecl `yaml:"commands,omitempty"`
	// Verification declares focused and full verification commands.
	Verification VerificationDecl `yaml:"verification,omitempty"`
	// ProtectedPaths lists paths agents must not modify without explicit
	// human approval, per ADR-0032's "generated and protected paths" and
	// docs/planning/agent-safety-policy.md's protected-paths list.
	ProtectedPaths []string `yaml:"protected_paths,omitempty"`
	// GeneratedPaths lists paths that are machine-generated and should
	// not be hand-edited (e.g. coverage output).
	GeneratedPaths []string `yaml:"generated_paths,omitempty"`
	// RequiredTools lists binaries this repository's declared commands
	// and checks depend on (e.g. "go", "git", "golangci-lint").
	RequiredTools []string `yaml:"required_tools,omitempty"`
	// OptionalServices lists external or optional services agents may
	// use when available.
	OptionalServices []OptionalService `yaml:"optional_services,omitempty"`
	// RequiredCredentials lists the *names* of secrets/credentials this
	// repository's workflows need (e.g. "GITHUB_TOKEN") — never their
	// values, per ADR-0032's "secret and credential requirements without
	// storing secret values." Validate additionally scans every string
	// field in this schema (including this one) for secret-shaped values
	// and fails if any are found; see secrets.go.
	RequiredCredentials []string `yaml:"required_credentials,omitempty"`
	// HandoffFormat names the schema/format an agent's handoff artifact
	// should conform to (e.g. "provenance.Envelope v1.0.0") — a reference
	// to that format by name, not a duplicate of its schema here.
	HandoffFormat string `yaml:"handoff_format,omitempty"`
}

type InstructionFile struct {
	// Path is the instruction file's location relative to the repository
	// root (e.g. "AGENTS.md").
	Path string `yaml:"path"`
	// Priority orders this file relative to other declared instruction
	// files: lower values take precedence. Ties should be resolved by the
	// Rule field below.
	Priority int `yaml:"priority"`
	// Notes is a short, human-readable description of what this file
	// covers or why it exists.
	Notes string `yaml:"notes,omitempty"`
}

type InstructionPrecedence struct {
	// Files lists every applicable instruction file, in no particular
	// slice order — Priority (and, for ties, Rule) determines precedence.
	Files []InstructionFile `yaml:"files,omitempty"`
	// Rule is a short, human-readable statement of the precedence rule
	// (e.g. which document wins when two disagree).
	Rule string `yaml:"rule,omitempty"`
}

type OptionalService struct {
	// Name is a short, stable identifier for this service (e.g.
	// "SonarCloud").
	Name string `yaml:"name"`
	// Description explains what the service provides and when it's used.
	Description string `yaml:"description,omitempty"`
}

type Project struct {
	// Name is a short, stable identifier for this project (e.g. "modulex").
	Name string `yaml:"name"`
	// Path is the project's root directory relative to the repository
	// root ("." for the repository root itself).
	Path string `yaml:"path"`
	// ModulePath is the Go module path declared in this project's go.mod
	// (e.g. "github.com/mediusfy/modulex"), if it is a Go module.
	ModulePath string `yaml:"module_path,omitempty"`
	// Description is a short, human-readable summary of this project's
	// purpose.
	Description string `yaml:"description,omitempty"`
	// CompositionRoots lists directories (relative to the repository
	// root) that wire this project's pieces together into a runnable
	// program (e.g. "examples/bootstrap").
	CompositionRoots []string `yaml:"composition_roots,omitempty"`
}

type VerificationDecl struct {
	// Focused lists checks recommended for a specific, scoped change.
	Focused []CheckDecl `yaml:"focused,omitempty"`
	// Full lists checks that are always required before push or release,
	// regardless of what changed.
	Full []CheckDecl `yaml:"full,omitempty"`
}