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

1"""Configuration of the verification ladder, certification and delivery hygiene (since 2.0, 

2issue #55). 

3 

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""" 

8 

9from __future__ import annotations 

10 

11import re 

12from pathlib import PurePosixPath 

13from typing import Any, Literal 

14 

15from pydantic import ( 

16 BaseModel, 

17 ConfigDict, 

18 Field, 

19 SerializerFunctionWrapHandler, 

20 field_validator, 

21 model_serializer, 

22 model_validator, 

23) 

24 

25from governed_harness.configuration.agent_results import off_from_yaml 

26from governed_harness.domain.enums import VerificationLevel 

27 

28_ENV_NAME = re.compile(r"^[A-Za-z_]\w{0,127}$", re.ASCII) 

29_BRANCH_FORBIDDEN = re.compile(r"(\.\.|[\s~^:?*\[\\]|@\{|//|^/|/$|\.lock$|^-)") 

30 

31 

32class _Section(BaseModel): 

33 """A section whose unset (``None``) keys are left out of the serialized configuration.""" 

34 

35 model_config = ConfigDict(extra="forbid", populate_by_name=True, frozen=True) 

36 

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 

45 

46 

47LadderMode = Literal["enforce", "warn", "off"] 

48DEFAULT_LADDER_LEVEL = VerificationLevel.L1 

49DEFAULT_DEFERRED_EXPIRY_DAYS = 14 

50DEFAULT_DETECTION_TIMEOUT_SECONDS = 10 

51 

52 

53class LadderConfig(_Section): 

54 """The verification ladder and certification (#55, items 1, 2, 4 and 6). 

55 

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.""" 

67 

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 ) 

76 

77 @field_validator("mode", mode="before") 

78 @classmethod 

79 def _bare_off(cls, value: Any) -> Any: 

80 return off_from_yaml(value) 

81 

82 @property 

83 def enabled(self) -> bool: 

84 return self.mode in {"enforce", "warn"} 

85 

86 @property 

87 def required_default(self) -> VerificationLevel: 

88 return self.default_level or DEFAULT_LADDER_LEVEL 

89 

90 @property 

91 def expiry_days(self) -> int: 

92 return self.deferred_expiry_days or DEFAULT_DEFERRED_EXPIRY_DAYS 

93 

94 @property 

95 def detection_timeout(self) -> int: 

96 return self.detection_timeout_seconds or DEFAULT_DETECTION_TIMEOUT_SECONDS 

97 

98 

99DEFAULT_MUTATION_HUNKS = 10 

100DEFAULT_MUTATION_SECONDS = 300 

101 

102 

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``.""" 

109 

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) 

113 

114 @field_validator("mode", mode="before") 

115 @classmethod 

116 def _bare_off(cls, value: Any) -> Any: 

117 return off_from_yaml(value) 

118 

119 @property 

120 def enabled(self) -> bool: 

121 return self.mode in {"enforce", "warn"} 

122 

123 @property 

124 def hunk_limit(self) -> int: 

125 return self.max_hunks or DEFAULT_MUTATION_HUNKS 

126 

127 @property 

128 def time_limit(self) -> int: 

129 return self.max_seconds or DEFAULT_MUTATION_SECONDS 

130 

131 

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 

140 

141 

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.""" 

146 

147 target: int | None = Field(default=None, ge=0, le=100) 

148 stop_conditions: tuple[StopCondition, ...] | None = Field(default=None, alias="stopConditions") 

149 

150 @property 

151 def effective_target(self) -> int: 

152 return DEFAULT_INTERRUPTION_TARGET if self.target is None else self.target 

153 

154 @property 

155 def conditions(self) -> tuple[StopCondition, ...]: 

156 return STOP_CONDITIONS if self.stop_conditions is None else self.stop_conditions 

157 

158 

159IsolationMode = Literal["none", "worktree"] 

160DEFAULT_ISOLATION_BRANCH = "harness/{taskId}-{runId}" 

161DEFAULT_ISOLATION_DIRECTORY = ".harness/worktrees" 

162 

163 

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.""" 

169 

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 

176 

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 

181 

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 

194 

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 

203 

204 @property 

205 def effective_mode(self) -> IsolationMode: 

206 return self.mode or "none" 

207 

208 @property 

209 def branch_template(self) -> str: 

210 return self.branch or DEFAULT_ISOLATION_BRANCH 

211 

212 @property 

213 def worktree_directory(self) -> str: 

214 return (self.directory or DEFAULT_ISOLATION_DIRECTORY).rstrip("/") 

215 

216 

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``.""" 

220 

221 name: str = Field(min_length=1, max_length=100) 

222 command: tuple[str, ...] = Field(min_length=1) 

223 pattern: str | None = None 

224 

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 

234 

235 

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.""" 

241 

242 required: tuple[str, ...] | None = None 

243 install: tuple[str, ...] | None = None 

244 

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 

252 

253 

254DirtyTreePolicy = Literal["allow", "warn", "block"] 

255BaselinePolicy = Literal["require", "report", "off"] 

256 

257 

258class EnvironmentConfig(_Section): 

259 """Generic environment preflight in DISCOVERY and ``harness doctor`` (#55, item 10). 

260 

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.""" 

268 

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 

274 

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 

282 

283 @field_validator("baseline", mode="before") 

284 @classmethod 

285 def _bare_off(cls, value: Any) -> Any: 

286 return off_from_yaml(value) 

287 

288 

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``.""" 

294 

295 create: bool | None = None 

296 draft: bool | None = None 

297 

298 

299CommentPolicy = Literal["notClean", "always", "never"] 

300 

301 

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.""" 

305 

306 files: tuple[str, ...] | None = None 

307 precedence: tuple[str, ...] | None = None 

308 

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 

317 

318 

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).""" 

328 

329 

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.""" 

333 

334 command: tuple[str, ...] | None = None 

335 expect: str | None = None 

336 path: str | None = None 

337 

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 

345 

346 

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.""" 

351 

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) 

359 

360 

361class ProfileVerification(_Section): 

362 """``verification`` of a technology profile: its capabilities per rung (#55, item 6).""" 

363 

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.""" 

368 

369 

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]