workspace

type BenchCfg struct {
	// History caps retained versions per unique benchmark key. Default 1:
	// the latest is what the codebase cares about (user requirement);
	// raise it to keep a benchmark history.
	History int `yaml:"history"`
}

type CompactCfg struct {
	JournalMax int `yaml:"journal_max"` // journal events since last compact
	DoneMax    int `yaml:"done_max"`    // done-but-unarchived items
}

type Config struct {
	Schema        string      `yaml:"schema"`
	Langs         []string    `yaml:"langs"`
	Ignore        []string    `yaml:"ignore"`       // glob patterns, repo-relative slash paths (see SkipDir)
	IgnoreRegex   []string    `yaml:"ignore_regex"` // RE2 patterns, matched against repo-relative slash paths
	BudgetDefault int         `yaml:"budget_default"`
	Compact       CompactCfg  `yaml:"compact"`
	Benchmarks    BenchCfg    `yaml:"benchmarks"`
	Verify        []string    `yaml:"verify"` // shell commands gating work-submit (e.g. "make test")
	Swarm         SwarmCfg    `yaml:"swarm"`
	WorktreesDir  string      `yaml:"worktrees_dir"` // override for .spectackle/wt (abs or root-relative)
	Feedback      FeedbackCfg `yaml:"feedback"`
	// CoverageGate: "package" makes check COUNT uncovered packages as
	// findings (CI red until backfilled) — explicit opt-in only. Top-level
	// rather than a FeedbackCfg sibling: it gates check's repository
	// hygiene, not the review loop's rounds (T-01KYD87ZN).
	CoverageGate string `yaml:"coverage_gate"`
	Git          GitCfg `yaml:"git"`
}

type FeedbackCfg struct {
	MaxRounds int    `yaml:"max_rounds"` // reopen attempts before an item escalates to blocked
	Grill     string `yaml:"grill"`      // "require" hard-gates approval on a passing review verdict; else warn
	Validate  string `yaml:"validate"`   // "require" hard-gates archive on a passing validation verdict; else warn (T-01KYD94M3)
	// Risk-gated require (T-01KYFXDCH): when Validate is NOT "require",
	// the archive gate still demands a verdict for items whose LANDED diff
	// (never declared targets — gameable, T-0135 landed 15 files against 4
	// declared) trips either input below. An explicit require is never
	// downgraded by these.
	RiskFiles      int      `yaml:"risk_files"`      // landed-file count that trips require; 0 = default 8
	DangerousPaths []string `yaml:"dangerous_paths"` // repo-relative globs ("dir/**" prefix or path.Match); default EMPTY — this repo's vocabulary is wrong for yours
}

type GitCfg struct {
	Enabled *bool  `yaml:"enabled"` // nil (key omitted) means true; see IsEnabled — a plain bool can't tell "omitted" from "explicitly false"
	Mode    string `yaml:"mode"`    // "offline" (default, GIT-DEFAULT-001: commit-only edges on the current branch) or "online" (explicit opt-in: branches, PRs, pushes to Remote); an unknown value is rejected at load, see load()
	Remote  string `yaml:"remote"`  // remote name pushed to in online mode; default "origin"
	Base    string `yaml:"base"`    // branch task branches are pushed against; default is the repository's OWN default branch, read at load (see wt.DefaultBranch) — never hardcoded "main"
	// Commits selects the edge-commit engine (T-01KYD94MG): "edges"
	// (default) commits every .spectackle-writing tool call with a
	// structured decision message derived from its journal events; "off"
	// produces zero commits and unchanged tool output (the validate
	// attribution fix that excludes spectackle( records subjects is
	// knob-independent and intended). A validator
	// argued the journal already carries eid/ag and the feature is
	// redundant; the requirement is explicit that the decision trail must
	// be readable in git log by humans, so the default stays edges and the
	// dissent is recorded on the task.
	Commits string `yaml:"commits"`

	// AwaitChecks is how many SECONDS the archive closure waits for the
	// head's CI verdict before refusing whole. It was a hardcoded 5 minutes,
	// which sat inside this repository's own CI duration distribution
	// (measured 3m43s-5m38s across ten consecutive runs) — so archives
	// refused on builds that were merely unfinished, and because a refusal
	// compensates by writing a journal event, the retry pushed a new commit
	// that started CI over. The wait could never converge
	// (B-01KYQJDJJVFC2).
	//
	// A knob rather than a bigger constant: the right value is a property of
	// the repository's CI, not of this program, and the code's own comment
	// already framed the budget as bounding damage rather than as a
	// correctness boundary. 0 or omitted means the default; see AwaitBudget.
	AwaitChecks int `yaml:"await_checks"`
}

type Locker interface {
	// WithLock runs fn while holding name, releasing on every exit path
	// (including panic). Callers pass the ENTIRE read-modify-write as fn,
	// never just the final write: locking only the write leaves two readers
	// racing to read the same stale state, which is the defect this exists
	// to close (B-01KYD57FN3ERHBM5EQ3534YJXP).
	WithLock(name string, fn func() error) error
}

type Root struct {
	// Sink, when set, observes every journal event this Root appends —
	// the edge-commit engine's exact capture mechanism (T-01KYD94MG): the
	// server installs a per-call buffer here in its gate, so the commit
	// derives from precisely the events the call wrote, never a glob of
	// everything dirty.
	Sink func(journalPath string, raw []byte)

	Dir   string // absolute path
	Agent string // agent identity writing through this workspace ("" outside swarm contexts)
	Cfg   Config

	// Lock is nil outside a swarm-aware caller (tests, migrate, a one-shot
	// CLI invocation with no coord.db open) — those already have at most one
	// writer touching any given bundle file, so item/spec/drift run unlocked
	// exactly as they always have. mcpserver.New sets it to the same *coord.DB
	// it opens for lease/counter/event coordination (see coord.go), so a
	// server process wires this up once at construction and every write
	// through the resulting Root is automatically serialized against
	// siblings — no call site elsewhere has to remember to ask for it.
	Lock Locker
}

type SwarmCfg struct {
	LeaseTTL int `yaml:"lease_ttl"` // seconds a scope lease lives without refresh
	AgentTTL int `yaml:"agent_ttl"` // seconds without heartbeat before an agent counts as gone
	// PanelMax CAPS a per-item multi-agent review panel (grill op=verdict
	// panel=n, legal only on live risk signals). Config can cap a panel,
	// never raise one that was not item-justified (P-01KYES kill list).
	PanelMax int `yaml:"panel_max"`
}