Coverage for src/governed_harness/configuration/ladder.py: 90%
201 statements
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
« prev ^ index » next coverage.py v7.17.2, created at 2026-11-12 16:06 +0000
1"""Configuration of the verification ladder, certification and delivery hygiene (since 2.0,
2issue #55).
4Every section and key here is optional. A key that is absent keeps the 1.0.0 behaviour and is
5left out of the serialized configuration, so the configuration snapshot (and its digest) of a
6project written before these settings existed does not change. ``harness init`` writes them.
7"""
9from __future__ import annotations
11import re
12from pathlib import PurePosixPath
13from typing import Any, Literal
15from pydantic import (
16 BaseModel,
17 ConfigDict,
18 Field,
19 SerializerFunctionWrapHandler,
20 field_validator,
21 model_serializer,
22 model_validator,
23)
25from governed_harness.configuration.agent_results import off_from_yaml
26from governed_harness.domain.enums import VerificationLevel
28_ENV_NAME = re.compile(r"^[A-Za-z_]\w{0,127}$", re.ASCII)
29_BRANCH_FORBIDDEN = re.compile(r"(\.\.|[\s~^:?*\[\\]|@\{|//|^/|/$|\.lock$|^-)")
32class _Section(BaseModel):
33 """A section whose unset (``None``) keys are left out of the serialized configuration."""
35 model_config = ConfigDict(extra="forbid", populate_by_name=True, frozen=True)
37 @model_serializer(mode="wrap")
38 def _omit_unset(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
39 data: dict[str, Any] = handler(self)
40 for name, field in type(self).model_fields.items():
41 if getattr(self, name) is None:
42 data.pop(name, None)
43 data.pop(field.alias or name, None)
44 return data
47LadderMode = Literal["enforce", "warn", "off"]
48DEFAULT_LADDER_LEVEL = VerificationLevel.L1
49DEFAULT_DEFERRED_EXPIRY_DAYS = 14
50DEFAULT_DETECTION_TIMEOUT_SECONDS = 10
53class LadderConfig(_Section):
54 """The verification ladder and certification (#55, items 1, 2, 4 and 6).
56 * ``mode``: ``enforce`` makes a criterion whose declared rung is not reached a ``HIGH``
57 finding (the gate fails until a person decides); ``warn`` makes it ``LOW``; ``off``
58 computes nothing.
59 * ``defaultLevel``: the rung a criterion without ``verification.level`` requires for the
60 certification status. Its gap is reported and never blocks: only a declared rung does.
61 * ``deferredExpiryDays``: how long a deferred verification may stay pending.
62 * ``preflight``: run the probes and the frozen acceptance tests on the baseline in PLANNING
63 and classify the run READY, PARTIAL or UNAVAILABLE before anything changes.
64 * ``capabilityDetection``: run the read-only detection commands of the profiles'
65 verification capabilities (a simulator, an emulator, a container engine), never an
66 installation."""
68 mode: LadderMode | None = None
69 default_level: VerificationLevel | None = Field(default=None, alias="defaultLevel")
70 deferred_expiry_days: int | None = Field(default=None, alias="deferredExpiryDays", ge=1, le=365)
71 preflight: bool | None = None
72 capability_detection: bool | None = Field(default=None, alias="capabilityDetection")
73 detection_timeout_seconds: int | None = Field(
74 default=None, alias="detectionTimeoutSeconds", ge=1, le=120
75 )
77 @field_validator("mode", mode="before")
78 @classmethod
79 def _bare_off(cls, value: Any) -> Any:
80 return off_from_yaml(value)
82 @property
83 def enabled(self) -> bool:
84 return self.mode in {"enforce", "warn"}
86 @property
87 def required_default(self) -> VerificationLevel:
88 return self.default_level or DEFAULT_LADDER_LEVEL
90 @property
91 def expiry_days(self) -> int:
92 return self.deferred_expiry_days or DEFAULT_DEFERRED_EXPIRY_DAYS
94 @property
95 def detection_timeout(self) -> int:
96 return self.detection_timeout_seconds or DEFAULT_DETECTION_TIMEOUT_SECONDS
99DEFAULT_MUTATION_HUNKS = 10
100DEFAULT_MUTATION_SECONDS = 300
103class MutationConfig(_Section):
104 """Discriminating evidence and light mutation (#55, item 5): new tests are classified by
105 running them on the baseline (fail before and pass after: discriminating; pass before and
106 after: weak; fail after: broken), and each changed hunk of the code is reverted in a scratch
107 copy, one at a time, to see that some test fails. ``enforce`` makes a change no test
108 exercises ``HIGH``, ``warn`` ``LOW``."""
110 mode: LadderMode | None = None
111 max_hunks: int | None = Field(default=None, alias="maxHunks", ge=1, le=100)
112 max_seconds: int | None = Field(default=None, alias="maxSeconds", ge=10, le=7200)
114 @field_validator("mode", mode="before")
115 @classmethod
116 def _bare_off(cls, value: Any) -> Any:
117 return off_from_yaml(value)
119 @property
120 def enabled(self) -> bool:
121 return self.mode in {"enforce", "warn"}
123 @property
124 def hunk_limit(self) -> int:
125 return self.max_hunks or DEFAULT_MUTATION_HUNKS
127 @property
128 def time_limit(self) -> int:
129 return self.max_seconds or DEFAULT_MUTATION_SECONDS
132ContractMode = Literal["enforce", "batch", "off"]
133StopCondition = Literal["unresolvable-ambiguity", "scope-contradiction", "destructive-collision"]
134STOP_CONDITIONS: tuple[StopCondition, ...] = (
135 "unresolvable-ambiguity",
136 "scope-contradiction",
137 "destructive-collision",
138)
139DEFAULT_INTERRUPTION_TARGET = 2
142class InterruptionConfig(_Section):
143 """The interruption budget of a run (#55, item 8): the number of human interactions the
144 run should need and the conditions under which the harness stops and asks a person.
145 Interactions are measured and reported; going over the target is reported, never hidden."""
147 target: int | None = Field(default=None, ge=0, le=100)
148 stop_conditions: tuple[StopCondition, ...] | None = Field(default=None, alias="stopConditions")
150 @property
151 def effective_target(self) -> int:
152 return DEFAULT_INTERRUPTION_TARGET if self.target is None else self.target
154 @property
155 def conditions(self) -> tuple[StopCondition, ...]:
156 return STOP_CONDITIONS if self.stop_conditions is None else self.stop_conditions
159IsolationMode = Literal["none", "worktree"]
160DEFAULT_ISOLATION_BRANCH = "harness/{taskId}-{runId}"
161DEFAULT_ISOLATION_DIRECTORY = ".harness/worktrees"
164class IsolationConfig(_Section):
165 """Worktree isolation per run (#55, item 9). ``mode: worktree`` (or ``run start --isolate
166 worktree``) creates a Git worktree on a new branch from the updated base branch and runs
167 the phases there; a branch or directory that already exists stops the run (BLOCKED), and
168 the harness never resets or deletes anything it did not create."""
170 mode: IsolationMode | None = None
171 branch: str | None = None
172 base: str | None = None
173 fetch: bool | None = None
174 remote: str | None = None
175 directory: str | None = None
177 @field_validator("mode", mode="before")
178 @classmethod
179 def _bare_none(cls, value: Any) -> Any:
180 return "none" if value is False or value == "off" else value
182 @field_validator("branch")
183 @classmethod
184 def _branch_template(cls, value: str | None) -> str | None:
185 if value is None: 185 ↛ 186line 185 didn't jump to line 186 because the condition on line 185 was never true
186 return value
187 sample = value.replace("{runId}", "run_x").replace("{taskId}", "task_x")
188 if not sample.strip() or _BRANCH_FORBIDDEN.search(sample) or "{" in sample: 188 ↛ 189line 188 didn't jump to line 189 because the condition on line 188 was never true
189 raise ValueError(
190 f"branch must be a valid branch name; only {{runId}} and {{taskId}} are "
191 f"replaced: {value!r}"
192 )
193 return value
195 @field_validator("directory")
196 @classmethod
197 def _relative_directory(cls, value: str | None) -> str | None:
198 if value is not None:
199 path = PurePosixPath(value.replace("\\", "/"))
200 if path.is_absolute() or ".." in path.parts or not value.strip():
201 raise ValueError(f"the worktree directory must be inside the workspace: {value!r}")
202 return value
204 @property
205 def effective_mode(self) -> IsolationMode:
206 return self.mode or "none"
208 @property
209 def branch_template(self) -> str:
210 return self.branch or DEFAULT_ISOLATION_BRANCH
212 @property
213 def worktree_directory(self) -> str:
214 return (self.directory or DEFAULT_ISOLATION_DIRECTORY).rstrip("/")
217class ToolRequirement(_Section):
218 """A tool the environment must provide: ``command`` prints its version and ``pattern`` (a
219 regular expression) must match the output, for example ``3\\.12``."""
221 name: str = Field(min_length=1, max_length=100)
222 command: tuple[str, ...] = Field(min_length=1)
223 pattern: str | None = None
225 @field_validator("pattern")
226 @classmethod
227 def _regex(cls, value: str | None) -> str | None:
228 if value is not None: 228 ↛ 233line 228 didn't jump to line 233 because the condition on line 228 was always true
229 try:
230 re.compile(value)
231 except re.error as error:
232 raise ValueError(f"invalid pattern {value!r}: {error}") from error
233 return value
236class GitHooksConfig(_Section):
237 """Git hooks the repository relies on: each must be present and executable (under
238 ``core.hooksPath`` when set). ``install`` is the command the project declares to install
239 them; the harness names it, and runs it only when a person asks (``harness doctor
240 --install-hooks``). Hooks are never bypassed."""
242 required: tuple[str, ...] | None = None
243 install: tuple[str, ...] | None = None
245 @field_validator("required")
246 @classmethod
247 def _hook_names(cls, value: tuple[str, ...] | None) -> tuple[str, ...] | None:
248 for name in value or ():
249 if not re.fullmatch(r"[a-z][a-z-]{1,40}", name): 249 ↛ 250line 249 didn't jump to line 250 because the condition on line 249 was never true
250 raise ValueError(f"not a Git hook name: {name!r}")
251 return value
254DirtyTreePolicy = Literal["allow", "warn", "block"]
255BaselinePolicy = Literal["require", "report", "off"]
258class EnvironmentConfig(_Section):
259 """Generic environment preflight in DISCOVERY and ``harness doctor`` (#55, item 10).
261 * ``tools``: tool versions the project requires;
262 * ``variables``: environment variables that must be set (names only, never values);
263 * ``gitHooks``: hooks that must be present and executable;
264 * ``dirtyTree``: what DISCOVERY does with uncommitted changes (``block``, ``warn``,
265 ``allow``);
266 * ``baseline``: run the mandatory validators on the baseline before the change: ``require``
267 blocks DISCOVERY when they do not pass, ``report`` records it."""
269 tools: tuple[ToolRequirement, ...] | None = None
270 variables: tuple[str, ...] | None = None
271 git_hooks: GitHooksConfig | None = Field(default=None, alias="gitHooks")
272 dirty_tree: DirtyTreePolicy | None = Field(default=None, alias="dirtyTree")
273 baseline: BaselinePolicy | None = None
275 @field_validator("variables")
276 @classmethod
277 def _names(cls, value: tuple[str, ...] | None) -> tuple[str, ...] | None:
278 for name in value or ():
279 if not _ENV_NAME.match(name): 279 ↛ 280line 279 didn't jump to line 280 because the condition on line 279 was never true
280 raise ValueError(f"not an environment variable name: {name!r}")
281 return value
283 @field_validator("baseline", mode="before")
284 @classmethod
285 def _bare_off(cls, value: Any) -> Any:
286 return off_from_yaml(value)
289class PullRequestConfig(_Section):
290 """``delivery.pullRequest``: create the pull or merge request of an approved run's branch
291 at CLOSURE (#55, item 13), when the operational contract authorises it. Where and how is
292 the forge's (``delivery.forge``, #56): the forge, the repository, ``baseBranch``, ``labels``
293 and ``template``; ``draft`` here takes precedence over ``delivery.forge.draft``."""
295 create: bool | None = None
296 draft: bool | None = None
299CommentPolicy = Literal["notClean", "always", "never"]
302class InstructionsConfig(_Section):
303 """``harness config lint`` (#55, item 14): the agent instruction files to read and their
304 precedence (``harness`` is the project configuration). The first entry wins a conflict."""
306 files: tuple[str, ...] | None = None
307 precedence: tuple[str, ...] | None = None
309 @field_validator("files")
310 @classmethod
311 def _relative(cls, value: tuple[str, ...] | None) -> tuple[str, ...] | None:
312 for item in value or ():
313 path = PurePosixPath(item.replace("\\", "/"))
314 if path.is_absolute() or ".." in path.parts or not item.strip(): 314 ↛ 315line 314 didn't jump to line 315 because the condition on line 314 was never true
315 raise ValueError(f"an instruction file must be relative: {item!r}")
316 return value
319DEFAULT_INSTRUCTION_FILES: tuple[str, ...] = (
320 "AGENTS.md",
321 "CLAUDE.md",
322 ".cursorrules",
323 ".cursor/rules",
324 ".github/copilot-instructions.md",
325)
326"""Agent instruction files ``harness config lint`` reads when ``instructions.files`` is not set
327(a directory such as ``.cursor/rules`` is read file by file)."""
330class CapabilityDetection(_Section):
331 """A read-only check that a capability is available: a command that must exit 0 (and,
332 with ``expect``, print a line matching it), or a path that must exist in the workspace."""
334 command: tuple[str, ...] | None = None
335 expect: str | None = None
336 path: str | None = None
338 @model_validator(mode="after")
339 def _one(self) -> CapabilityDetection:
340 if (self.command is None) == (self.path is None): 340 ↛ 341line 340 didn't jump to line 341 because the condition on line 340 was never true
341 raise ValueError("a detection needs exactly one of command or path")
342 if self.expect is not None:
343 re.compile(self.expect)
344 return self
347class VerificationCapability(_Section):
348 """What a profile offers at one rung of the ladder: the validators whose passing result
349 establishes it, the read-only detections that tell whether it is available here, and the
350 rung to fall back to when it is not."""
352 level: VerificationLevel
353 provides: str = Field(min_length=1, max_length=500)
354 validators: tuple[str, ...] | None = None
355 detect: tuple[CapabilityDetection, ...] | None = None
356 probes: bool | None = None
357 """The rung is reached through declared probes (L3, L4)."""
358 fallback: str | None = Field(default=None, max_length=500)
361class ProfileVerification(_Section):
362 """``verification`` of a technology profile: its capabilities per rung (#55, item 6)."""
364 capabilities: tuple[VerificationCapability, ...] | None = None
365 mutation_command: tuple[str, ...] | None = Field(default=None, alias="mutationCommand")
366 """The command that runs a list of test files (``{paths}`` is replaced by them): light
367 mutation and the classification of new tests use it."""
370__all__ = [
371 "DEFAULT_INSTRUCTION_FILES",
372 "STOP_CONDITIONS",
373 "BaselinePolicy",
374 "CapabilityDetection",
375 "CommentPolicy",
376 "ContractMode",
377 "DirtyTreePolicy",
378 "EnvironmentConfig",
379 "GitHooksConfig",
380 "InstructionsConfig",
381 "InterruptionConfig",
382 "IsolationConfig",
383 "LadderConfig",
384 "MutationConfig",
385 "ProfileVerification",
386 "PullRequestConfig",
387 "ToolRequirement",
388 "VerificationCapability",
389]