Coverage for src/governed_harness/orchestration/architecture.py: 87%

451 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-12 16:06 +0000

1"""Architecture of the project: survey, options, decision and layer rules (#56). 

2 

3* **Existing project** (``architecture.mode: agent``): DISCOVERY makes one read-only 

4 ``architecture`` call (``mode: survey``) per project. The answer (the patterns in use and the 

5 layer rules they imply) is cached in ``.harness/architecture.md`` and 

6 ``.harness/architecture.json``, keyed by the digest of the source directory layout, and reused 

7 by every later run without another call. When it infers layer rules, DISCOVERY waits until a 

8 person approves or rejects them, bound to their digest (``harness architecture decide``). The 

9 survey runs again only on demand (``harness architecture refresh``) or, under 

10 ``refresh: auto``, when the layout changed materially (fewer than 80 % of the source 

11 directories in common). 

12* **New project**: INTENT makes one ``architecture`` call (``mode: advise``) for options with 

13 trade-offs (DDD, hexagonal, clean, layered, modular monolith, microservices, MVVM, MVI). A 

14 person chooses one (``harness architecture decide --option``), bound to the digest of the 

15 options; the choice is recorded as an ADR (an artifact with its digest, and 

16 ``.harness/adr/ADR-0001-architecture.md``) and its layer rules become the project's. 

17* **Configured layers** (``architecture.layers`` and ``allow``) are the rules as written; no call. 

18 

19The rules are enforced in VERIFICATION by the layer check (``harness.layers``, rule 

20``architecture.layer-violation``), the #40 forbidden-dependency check generalized to every 

21language the standards packs know. 

22 

23Since 2.0 (#93), under ``architecture.baselineConflicts: allow`` the rules a survey infers are 

24checked against the code as it is before they are proposed: a dependency between two layers that 

25the rules forbid and the baseline already has is a conflict. The proposal lists the conflicts 

26(``baselineConflicts``, with examples) and carries the rules that will be in force 

27(``enforced``: the inferred rules with those dependencies allowed), both under the digest a person 

28approves, so a rule the project itself breaks is seen when it is proposed and is not enforced as 

29it was written.""" 

30 

31from __future__ import annotations 

32 

33import json 

34from pathlib import Path 

35from typing import TYPE_CHECKING, Any 

36 

37from governed_harness.agents.requests import ADVISE_CATALOGUE_SUFFIX 

38from governed_harness.checks.layers import LayerRules, crossings 

39from governed_harness.checks.principles import is_source 

40from governed_harness.configuration.engineering import ( 

41 ARCHITECTURE_STYLES, 

42 BASE_STYLES, 

43 CATALOGUE_STYLES, 

44 ArchitectureSettings, 

45) 

46from governed_harness.domain.enums import ActorType, DecisionKind, PhaseId, ResultStatus 

47from governed_harness.domain.errors import NotFoundError, PolicyViolationError 

48from governed_harness.domain.models import Actor, Execution, PhaseExecution, Task, utc_now 

49from governed_harness.evidence.hashing import sha256_json 

50from governed_harness.intake.project_kind import ProjectKind, detect_project_kind 

51from governed_harness.orchestration import reverse_engineering 

52from governed_harness.orchestration.architecture_catalogue import ( 

53 ORGANIZATION_FILE, 

54 RECOMMENDATION_FILE, 

55 STYLE_DOC_FILE, 

56 catalogue, 

57 expert_block, 

58 in_catalogue, 

59 render_recommendation, 

60 style_entry, 

61) 

62from governed_harness.orchestration.engine_types import AgentCallOutcome, PhaseOutcome 

63from governed_harness.runtime.workspace import DEFAULT_EXCLUDES 

64 

65if TYPE_CHECKING: 

66 from governed_harness.orchestration.hosts import ResultsHost 

67 

68STATE_FILE = "architecture.json" 

69SURVEY_FILE = "architecture.md" 

70ADR_FILE = "adr/ADR-0001-architecture.md" 

71MATERIAL_CHANGE = 0.8 

72"""Under ``refresh: auto`` the survey runs again when fewer than this share of the source 

73directories is common to the cached layout and the current one (Jaccard similarity).""" 

74_MAX_LAYOUT = 400 

75_MAX_LAYERS = 20 

76_MAX_SOURCES = 5000 

77_MAX_SOURCE_BYTES = 1_000_000 

78_MAX_EXAMPLES = 5 

79 

80 

81# ----- layout --------------------------------------------------------------------------------- 

82def source_layout(workspace: Path, depth: int = 4) -> list[str]: 

83 """The directories (up to ``depth`` levels) that hold source files, sorted.""" 

84 root = workspace.resolve() 

85 found: set[str] = set() 

86 stack: list[tuple[Path, int]] = [(root, 0)] 

87 while stack and len(found) < _MAX_LAYOUT: 

88 directory, level = stack.pop() 

89 try: 

90 entries = sorted(directory.iterdir(), key=lambda item: item.name) 

91 except OSError: 

92 continue 

93 visible = [entry for entry in entries if not _hidden(entry)] 

94 if level < depth: 94 ↛ 96line 94 didn't jump to line 96 because the condition on line 94 was always true

95 stack.extend((entry, level + 1) for entry in visible if entry.is_dir()) 

96 if any(entry.is_file() and is_source(entry.name) for entry in visible): 

97 found.add(directory.relative_to(root).as_posix() or ".") 

98 return sorted(found) 

99 

100 

101def _hidden(entry: Path) -> bool: 

102 """An excluded, hidden or symbolic-link entry the layout does not look into.""" 

103 return entry.name in DEFAULT_EXCLUDES or entry.name.startswith(".") or entry.is_symlink() 

104 

105 

106def similarity(left: list[str], right: list[str]) -> float: 

107 a, b = set(left), set(right) 

108 if not a and not b: 108 ↛ 109line 108 didn't jump to line 109 because the condition on line 108 was never true

109 return 1.0 

110 return len(a & b) / len(a | b) 

111 

112 

113# ----- the rules against the baseline (#93) ------------------------------------------------------- 

114def baseline_sources(workspace: Path) -> dict[str, str]: 

115 """The text of the source files of the workspace (hidden and excluded directories and 

116 symbolic links left out), by workspace-relative path.""" 

117 root = workspace.resolve() 

118 files: dict[str, str] = {} 

119 stack: list[Path] = [root] 

120 while stack and len(files) < _MAX_SOURCES: 

121 directory = stack.pop() 

122 try: 

123 entries = sorted(directory.iterdir(), key=lambda item: item.name) 

124 except OSError: 

125 continue 

126 visible = [entry for entry in entries if not _hidden(entry)] 

127 stack.extend(entry for entry in visible if entry.is_dir()) 

128 for entry in visible: 

129 if entry.is_file() and is_source(entry.name): 

130 _read_source(files, root, entry) 

131 return files 

132 

133 

134def _read_source(files: dict[str, str], root: Path, entry: Path) -> None: 

135 try: 

136 if entry.stat().st_size <= _MAX_SOURCE_BYTES: 136 ↛ exitline 136 didn't return from function '_read_source' because the condition on line 136 was always true

137 files[entry.relative_to(root).as_posix()] = entry.read_text(encoding="utf-8") 

138 except (OSError, UnicodeDecodeError): 

139 return 

140 

141 

142def baseline_conflicts(files: dict[str, str], rules: dict[str, Any]) -> list[dict[str, Any]]: 

143 """The dependencies between layers that ``rules`` forbid and ``files`` already have: one 

144 entry per pair of layers, with the number of imports and a few examples.""" 

145 layer_rules = LayerRules.from_mapping(rules.get("layers") or [], rules.get("allow") or {}) 

146 grouped: dict[tuple[str, str], list[dict[str, Any]]] = {} 

147 for item in crossings(files, layer_rules): 

148 grouped.setdefault((item.source, item.layer), []).append( 

149 {"path": item.path, "line": item.line, "target": item.target} 

150 ) 

151 return [ 

152 {"from": source, "to": target, "imports": len(found), "examples": found[:_MAX_EXAMPLES]} 

153 for (source, target), found in sorted(grouped.items()) 

154 ] 

155 

156 

157def allowing(rules: dict[str, Any], conflicts: list[dict[str, Any]]) -> dict[str, Any]: 

158 """``rules`` with the dependencies of ``conflicts`` added to ``allow``.""" 

159 allow = {str(key): list(value) for key, value in (rules.get("allow") or {}).items()} 

160 for item in conflicts: 

161 targets = allow.setdefault(item["from"], []) 

162 if item["to"] not in targets: 162 ↛ 160line 162 didn't jump to line 160 because the condition on line 162 was always true

163 targets.append(item["to"]) 

164 return {"layers": rules.get("layers") or [], "allow": allow} 

165 

166 

167def conflicts_summary(state: dict[str, Any]) -> str: 

168 """One sentence about the conflicts of a proposal, empty when it has none.""" 

169 conflicts = state.get("baselineConflicts") or [] 

170 if not conflicts: 

171 return "" 

172 shown = ", ".join( 

173 f"{item['from']} -> {item['to']} ({item['imports']} import(s))" for item in conflicts[:10] 

174 ) 

175 return ( 

176 f"the code already breaks {len(conflicts)} inferred rule(s): {shown}; these dependencies " 

177 "stay allowed if you approve (harness architecture show lists them)" 

178 ) 

179 

180 

181# ----- validation of the agent's answers ---------------------------------------------------------- 

182def _layer(item: Any) -> dict[str, Any]: 

183 """One layer of an answer: a normalised name and relative path globs or modules.""" 

184 if not isinstance(item, dict) or not str(item.get("name") or "").strip(): 184 ↛ 185line 184 didn't jump to line 185 because the condition on line 184 was never true

185 raise ValueError("every layer needs a name") 

186 name = "".join( 

187 char if char.isalnum() or char in "-_" else "-" for char in str(item["name"]).lower() 

188 )[:40] 

189 paths = [str(path) for path in item.get("paths") or [] if str(path).strip()] 

190 modules = [str(module) for module in item.get("modules") or [] if str(module).strip()] 

191 if any(path.startswith("/") or ".." in path.split("/") for path in paths): 191 ↛ 192line 191 didn't jump to line 192 because the condition on line 191 was never true

192 raise ValueError(f"layer {name}: paths must be relative globs") 

193 if not paths and not modules: 193 ↛ 194line 193 didn't jump to line 194 because the condition on line 193 was never true

194 raise ValueError(f"layer {name} needs paths or modules") 

195 return {"name": name, "paths": paths, "modules": modules} 

196 

197 

198def _allow(raw: Any, names: set[str]) -> dict[str, list[str]]: 

199 """The allowed dependencies of an answer, between the layers it names.""" 

200 allow: dict[str, list[str]] = {} 

201 if not isinstance(raw, dict): 201 ↛ 202line 201 didn't jump to line 202 because the condition on line 201 was never true

202 return allow 

203 for key, targets in raw.items(): 

204 source = str(key).lower() 

205 listed = [str(item).lower() for item in targets or []] if isinstance(targets, list) else [] 

206 unknown = [item for item in (source, *listed) if item not in names] 

207 if unknown: 207 ↛ 208line 207 didn't jump to line 208 because the condition on line 207 was never true

208 raise ValueError(f"allow names unknown layer(s): {', '.join(sorted(set(unknown)))}") 

209 allow[source] = listed 

210 return allow 

211 

212 

213def _layers(value: Any) -> tuple[list[dict[str, Any]], dict[str, list[str]]]: 

214 raw = value.get("layers") if isinstance(value, dict) else None 

215 layers = [_layer(item) for item in (raw if isinstance(raw, list) else [])] 

216 if len(layers) > _MAX_LAYERS: 216 ↛ 217line 216 didn't jump to line 217 because the condition on line 216 was never true

217 raise ValueError(f"at most {_MAX_LAYERS} layers") 

218 allow_raw = value.get("allow") if isinstance(value, dict) else None 

219 return layers, _allow(allow_raw, {item["name"] for item in layers}) 

220 

221 

222def validate_survey(result: dict[str, Any]) -> dict[str, Any]: 

223 style = str(result.get("style") or "custom").strip().lower() 

224 if style not in ARCHITECTURE_STYLES: 224 ↛ 225line 224 didn't jump to line 225 because the condition on line 224 was never true

225 style = "custom" 

226 summary = result.get("summary") 

227 if not isinstance(summary, str): 227 ↛ 228line 227 didn't jump to line 228 because the condition on line 227 was never true

228 raise ValueError("the survey needs a 'summary' text") 

229 layers, allow = _layers(result) 

230 return {"style": style, "summary": summary.strip()[:20_000], "layers": layers, "allow": allow} 

231 

232 

233def validate_options(result: dict[str, Any]) -> list[dict[str, Any]]: 

234 raw = result.get("options") 

235 if not isinstance(raw, list): 235 ↛ 236line 235 didn't jump to line 236 because the condition on line 235 was never true

236 raise ValueError("the advice needs an 'options' list") 

237 options = [_option(index, item) for index, item in enumerate(raw[:6], start=1)] 

238 ids = [item["id"] for item in options] 

239 if len(ids) != len(set(ids)): 239 ↛ 240line 239 didn't jump to line 240 because the condition on line 239 was never true

240 raise ValueError("option ids must be unique") 

241 return options 

242 

243 

244def _option(index: int, item: Any) -> dict[str, Any]: 

245 """One validated option of the advice (the ``index`` counts from 1).""" 

246 if not isinstance(item, dict): 246 ↛ 247line 246 didn't jump to line 247 because the condition on line 246 was never true

247 raise ValueError(f"option {index} is not an object") 

248 style = str(item.get("style") or "").strip().lower() 

249 if style not in ARCHITECTURE_STYLES: 249 ↛ 250line 249 didn't jump to line 250 because the condition on line 249 was never true

250 raise ValueError(f"option {index} has an unknown style {item.get('style')!r}") 

251 layers, allow = _layers(item) 

252 option = { 

253 "id": str(item.get("id") or f"option-{index}")[:40], 

254 "style": style, 

255 "title": str(item.get("title") or style)[:200], 

256 "benefits": [str(text)[:400] for text in item.get("benefits") or []][:10], 

257 "costs": [str(text)[:400] for text in item.get("costs") or []][:10], 

258 "fit": str(item.get("fit") or "")[:1000], 

259 "recommended": bool(item.get("recommended")), 

260 "layers": layers, 

261 "allow": allow, 

262 } 

263 if "supports" in item: # the catalogue (#97); absent keeps the earlier options and digest 

264 option["supports"] = [str(text)[:400] for text in item.get("supports") or []][:10] 

265 return option 

266 

267 

268def validate_catalogue_options(result: dict[str, Any]) -> list[dict[str, Any]]: 

269 """The options of an advise call under ``architecture.catalogue: experts``: styles of the 

270 catalogue, the reasons and project characteristics behind each, and exactly one 

271 recommended, so the report a person reads is complete (fail closed).""" 

272 options = validate_options(result) 

273 for item in options: 

274 if not in_catalogue(item["style"]): 274 ↛ 275line 274 didn't jump to line 275 because the condition on line 274 was never true

275 raise ValueError(f"option {item['id']} is not a style of the catalogue") 

276 if not item["fit"].strip() or not item.get("supports"): 

277 raise ValueError(f"option {item['id']} needs a 'fit' reason and 'supports'") 

278 if options and sum(1 for item in options if item["recommended"]) != 1: 278 ↛ 279line 278 didn't jump to line 279 because the condition on line 278 was never true

279 raise ValueError("mark exactly one option as recommended") 

280 return options 

281 

282 

283def validate_organization(result: dict[str, Any]) -> dict[str, Any]: 

284 """The plan of the expert for the chosen style: where things go and the practices to apply.""" 

285 summary = result.get("summary") 

286 structure = result.get("structure") 

287 practices = result.get("practices") 

288 if not isinstance(summary, str) or not summary.strip(): 288 ↛ 289line 288 didn't jump to line 289 because the condition on line 288 was never true

289 raise ValueError("the organization needs a 'summary' text") 

290 if not isinstance(structure, list) or not isinstance(practices, list): 290 ↛ 291line 290 didn't jump to line 291 because the condition on line 290 was never true

291 raise ValueError("the organization needs 'structure' and 'practices' lists") 

292 entries = [ 

293 {"path": str(item.get("path") or "")[:300], "purpose": str(item.get("purpose") or "")[:400]} 

294 for item in structure[:60] 

295 if isinstance(item, dict) and str(item.get("path") or "").strip() 

296 ] 

297 if any(item["path"].startswith("/") or ".." in item["path"].split("/") for item in entries): 297 ↛ 298line 297 didn't jump to line 298 because the condition on line 297 was never true

298 raise ValueError("structure paths must be relative") 

299 return { 

300 "summary": summary.strip()[:20_000], 

301 "structure": entries, 

302 "practices": [str(text)[:400] for text in practices[:20]], 

303 } 

304 

305 

306def validate_documented_survey(result: dict[str, Any]) -> dict[str, Any]: 

307 """A survey answer with the reverse engineering documentation (``documentation: project``).""" 

308 survey = validate_survey(result) 

309 survey["documentation"] = reverse_engineering.validate_documentation(result) 

310 return survey 

311 

312 

313def render_adr(option: dict[str, Any], *, decided_by: str, rationale: str, digest: str) -> str: 

314 """The architecture decision record of a chosen option (Markdown).""" 

315 lines = [ 

316 f"# ADR-0001: {option['title']}", 

317 "", 

318 "Status: accepted", 

319 f"Decided by: {decided_by}", 

320 f"Options digest: {digest}", 

321 "", 

322 "## Decision", 

323 "", 

324 f"The project follows the {option['style']} style ({option['id']}). {rationale}", 

325 "", 

326 "## Consequences", 

327 "", 

328 *[f"- Benefit: {item}" for item in option["benefits"]], 

329 *[f"- Cost: {item}" for item in option["costs"]], 

330 "", 

331 "## Layer rules", 

332 "", 

333 ] 

334 for layer in option["layers"]: 

335 allowed = ", ".join(option["allow"].get(layer["name"], [])) or "no other layer" 

336 where = ", ".join([*layer["paths"], *layer["modules"]]) 

337 lines.append(f"- {layer['name']} ({where}) may depend on: {allowed}") 

338 return "\n".join(lines).rstrip() + "\n" 

339 

340 

341def _recommended(options: list[dict[str, Any]]) -> str: 

342 """The id of the recommended option (the first one when none is marked).""" 

343 marked = [item["id"] for item in options if item.get("recommended")] 

344 return str(marked[0] if marked else options[0]["id"]) 

345 

346 

347def _render_organization(title: str, plan: dict[str, Any]) -> str: 

348 """The plan of the expert for the chosen style (Markdown).""" 

349 lines = [ 

350 f"# Organization of the project ({title})", 

351 "", 

352 plan["summary"], 

353 "", 

354 "## Structure", 

355 "", 

356 ] 

357 lines += [f"- `{item['path']}`: {item['purpose']}" for item in plan["structure"]] 

358 lines += ["", "## Practices", "", *[f"- {item}" for item in plan["practices"]]] 

359 return "\n".join(lines).rstrip() + "\n" 

360 

361 

362# ----- the flow --------------------------------------------------------------------------------------- 

363class ArchitectureFlow: 

364 def __init__(self, results: ResultsHost) -> None: 

365 self.results = results 

366 

367 @property 

368 def config(self) -> ArchitectureSettings | None: 

369 return self.results.project.architecture 

370 

371 @property 

372 def harness_dir(self) -> Path: 

373 return self.results.s.paths.harness_dir 

374 

375 def state(self) -> dict[str, Any] | None: 

376 return read_state(self.harness_dir) 

377 

378 def _write(self, value: dict[str, Any]) -> None: 

379 write_state(self.harness_dir, value) 

380 

381 def kind(self) -> ProjectKind: 

382 return detect_project_kind(self.results.s.paths.workspace) 

383 

384 # ----- the rules in force ------------------------------------------------------------------ 

385 def rules(self) -> LayerRules | None: 

386 return effective_rules(self.config, self.harness_dir) 

387 

388 def request_extra(self) -> dict[str, Any] | None: 

389 rules = self.rules() 

390 state = self.state() or {} 

391 block: dict[str, Any] = {} 

392 if rules is not None and rules.layers: 

393 block = { 

394 "style": (self.config.style if self.config and self.config.style else None) 

395 or state.get("style"), 

396 **rules.as_dict(), 

397 } 

398 block.update(self._guidance(state)) 

399 return block or None 

400 

401 def _guidance(self, state: dict[str, Any]) -> dict[str, Any]: 

402 """What the requests carry besides the rules (#97): the expert prompt of the chosen 

403 style and its organisation (``catalogue: experts``), and where the reverse engineering 

404 documents of an existing project are (``documentation: project``).""" 

405 config = self.config 

406 if config is None: 

407 return {} 

408 extra: dict[str, Any] = {} 

409 style = state.get("style") 

410 if ( 

411 config.experts 

412 and state.get("status") == "APPROVED" 

413 and isinstance(style, str) 

414 and in_catalogue(style) 

415 ): 

416 extra["style"] = style 

417 extra["expert"] = expert_block(style) 

418 organization = state.get("organization") 

419 if isinstance(organization, dict): 419 ↛ 421line 419 didn't jump to line 421 because the condition on line 419 was always true

420 extra["organization"] = organization.get("summary") 

421 if config.documents: 

422 docs = reverse_engineering.request_block(self.harness_dir, state.get("documentation")) 

423 if docs is not None: 423 ↛ 425line 423 didn't jump to line 425 because the condition on line 423 was always true

424 extra["reverseEngineering"] = docs 

425 return extra 

426 

427 def _styles(self, *, full: bool = False) -> tuple[str, ...]: 

428 """The styles listed in the requests: the catalogue (advise) or the earlier list.""" 

429 if self.config is not None and self.config.experts: 

430 return ARCHITECTURE_STYLES if full else CATALOGUE_STYLES 

431 return BASE_STYLES 

432 

433 # ----- INTENT: options for a new project ------------------------------------------------- 

434 def advise( 

435 self, execution: Execution, phase: PhaseExecution, task: Task 

436 ) -> PhaseOutcome | None: 

437 config = self.config 

438 if config is None or not config.agent_enabled or config.layers or config.style: 

439 return None 

440 state = self.state() 

441 status = state.get("status") if state is not None else None 

442 if state is not None and status == "APPROVED" and config.experts: 

443 return self._organize(execution, phase, task, state) 

444 if status in {"APPROVED", "REJECTED", "NONE"}: 

445 return None 

446 if state is not None and status == "OPTIONS": 446 ↛ 447line 446 didn't jump to line 447 because the condition on line 446 was never true

447 return self._waiting(execution, state) 

448 kind = self.kind() 

449 if not kind.new: 

450 return None 

451 outcome = self._advice_call(execution, phase, task, kind, config) 

452 if outcome.status is not ResultStatus.PASSED or outcome.result is None: 452 ↛ 453line 452 didn't jump to line 453 because the condition on line 452 was never true

453 return PhaseOutcome( 

454 ResultStatus.BLOCKED, 

455 f"The architecture call did not answer ({outcome.status}): {outcome.summary}", 

456 outcome.evidence_refs, 

457 ) 

458 try: 

459 options = ( 

460 validate_catalogue_options(outcome.result) 

461 if config.experts 

462 else validate_options(outcome.result) 

463 ) 

464 except ValueError as error: 

465 return self._malformed(execution, error, outcome.evidence_refs) 

466 return self._proposed(execution, phase, kind, outcome, options) 

467 

468 def _advice_call( 

469 self, 

470 execution: Execution, 

471 phase: PhaseExecution, 

472 task: Task, 

473 kind: ProjectKind, 

474 config: ArchitectureSettings, 

475 ) -> Any: 

476 """The advise call: the earlier request, or under ``catalogue: experts`` the ten styles 

477 with what each one is for and the report fields a person needs to decide.""" 

478 styles = self._styles() 

479 payload: dict[str, Any] = { 

480 "mode": "advise", 

481 "styles": list(styles), 

482 "projectKind": kind.as_dict(), 

483 } 

484 suffix = "" 

485 if config.experts: 

486 payload["catalogue"] = [item.summary() for item in catalogue()] 

487 suffix = ADVISE_CATALOGUE_SUFFIX 

488 return self.results.call_agent( 

489 execution, 

490 phase, 

491 "architecture", 

492 payload, 

493 task=task, 

494 instruction_values={"mode": "advise", "styles": ", ".join(styles)}, 

495 instructions_suffix=suffix, 

496 validate=validate_catalogue_options if config.experts else validate_options, 

497 ) 

498 

499 def _proposed( 

500 self, 

501 execution: Execution, 

502 phase: PhaseExecution, 

503 kind: ProjectKind, 

504 outcome: Any, 

505 options: list[dict[str, Any]], 

506 ) -> PhaseOutcome | None: 

507 """Record the options (and, with the catalogue, the report a person reads).""" 

508 digest = sha256_json({"options": options}) 

509 record = { 

510 "status": "OPTIONS" if options else "NONE", 

511 "mode": "advise", 

512 "digest": digest, 

513 "options": options, 

514 "projectKind": kind.as_dict(), 

515 "invocationId": outcome.invocation_id, 

516 "createdAt": utc_now().isoformat(), 

517 } 

518 ref = self.results.record_json( 

519 execution, 

520 PhaseId.INTENT, 

521 record, 

522 kind="architecture-options", 

523 summary=f"Architecture options for a new project: {len(options)}", 

524 ) 

525 self._write({**record, "ref": ref, "executionId": execution.execution_id}) 

526 payload: dict[str, Any] = { 

527 "digest": digest, 

528 "options": [item["id"] for item in options], 

529 "evidenceRef": ref, 

530 } 

531 if self.config is not None and self.config.experts and options: 

532 (self.harness_dir / RECOMMENDATION_FILE).write_text( 

533 render_recommendation(options, kind.as_dict()), encoding="utf-8" 

534 ) 

535 payload["recommended"] = _recommended(options) 

536 self.results.s.events.append( 

537 execution.execution_id, 

538 "architecture.options.proposed", 

539 payload, 

540 phase_execution_id=phase.phase_execution_id, 

541 ) 

542 if not options: 542 ↛ 543line 542 didn't jump to line 543 because the condition on line 542 was never true

543 return None 

544 return self._waiting(execution, {**record, "ref": ref}) 

545 

546 def _waiting(self, execution: Execution, state: dict[str, Any]) -> PhaseOutcome: 

547 """The options wait for a person; with the catalogue the message names the recommended 

548 one and the report to read.""" 

549 text = ( 

550 f"{len(state['options'])} architecture option(s) wait for a person: harness " 

551 f"architecture decide --run {execution.execution_id} --option <id> --digest " 

552 f"{state['digest']}" 

553 ) 

554 if self.config is not None and self.config.experts: 

555 text += ( 

556 f" (recommended: {_recommended(state['options'])}; the report is " 

557 f".harness/{RECOMMENDATION_FILE}; --style <style> chooses any style of the " 

558 "catalogue)" 

559 ) 

560 return PhaseOutcome(ResultStatus.BLOCKED, text, (state["ref"],)) 

561 

562 def _organize( 

563 self, execution: Execution, phase: PhaseExecution, task: Task, state: dict[str, Any] 

564 ) -> PhaseOutcome | None: 

565 """Once the style is chosen, one call by its expert plans how the project is organised 

566 (the read-only plan the implementation then follows); recorded in the state, so it is 

567 not asked again.""" 

568 style = state.get("style") 

569 if state.get("mode") != "advise" or "organization" in state or not in_catalogue(style): 

570 return None 

571 entry = style_entry(str(style)) 

572 outcome = self.results.call_agent( 

573 execution, 

574 phase, 

575 "architecture", 

576 {"mode": "organize", "style": entry.style, "rules": state.get("rules") or {}}, 

577 task=task, 

578 instruction_values={"mode": "organize", "style": entry.title}, 

579 instructions_suffix=entry.expert_prompt, 

580 validate=validate_organization, 

581 ) 

582 if outcome.status is not ResultStatus.PASSED or outcome.result is None: 582 ↛ 583line 582 didn't jump to line 583 because the condition on line 582 was never true

583 return PhaseOutcome( 

584 ResultStatus.BLOCKED, 

585 f"The {entry.style} expert did not answer ({outcome.status}): {outcome.summary}", 

586 outcome.evidence_refs, 

587 ) 

588 try: 

589 plan = validate_organization(outcome.result) 

590 except ValueError as error: 

591 return self._malformed(execution, error, outcome.evidence_refs) 

592 organization = {**plan, "digest": sha256_json(plan), "invocationId": outcome.invocation_id} 

593 ref = self.results.record_json( 

594 execution, 

595 PhaseId.INTENT, 

596 {"style": entry.style, **organization}, 

597 kind="architecture-organization", 

598 summary=f"Organization of the project by the {entry.style} expert", 

599 ) 

600 (self.harness_dir / ORGANIZATION_FILE).write_text( 

601 _render_organization(entry.title, plan), encoding="utf-8" 

602 ) 

603 self._write({**state, "organization": {**organization, "ref": ref}}) 

604 self.results.s.events.append( 

605 execution.execution_id, 

606 "architecture.organization.proposed", 

607 {"style": entry.style, "digest": organization["digest"], "evidenceRef": ref}, 

608 phase_execution_id=phase.phase_execution_id, 

609 ) 

610 return None 

611 

612 # ----- DISCOVERY: survey of an existing project ------------------------------------------ 

613 def survey( 

614 self, execution: Execution, phase: PhaseExecution, task: Task 

615 ) -> PhaseOutcome | None: 

616 config = self.config 

617 if config is None or not config.agent_enabled or config.layers: 

618 return None 

619 layout = source_layout(self.results.s.paths.workspace) 

620 state = self.state() 

621 if state is not None and state.get("mode") == "advise": 

622 return None # a new project: the ADR decides 

623 if state is not None and state.get("status") == "PROPOSED": 623 ↛ 624line 623 didn't jump to line 624 because the condition on line 623 was never true

624 return PhaseOutcome( 

625 ResultStatus.BLOCKED, 

626 "The inferred architecture rules wait for a person: harness architecture decide " 

627 f"--run {execution.execution_id} --decision APPROVE --digest {state['digest']}", 

628 (state["ref"],), 

629 ) 

630 if state is not None and self._reused(execution, phase, config, state, layout): 

631 return None 

632 if self.kind().new: 632 ↛ 633line 632 didn't jump to line 633 because the condition on line 632 was never true

633 return None 

634 validate = validate_documented_survey if config.documents else validate_survey 

635 styles = self._styles(full=True) 

636 outcome = self.results.call_agent( 

637 execution, 

638 phase, 

639 "architecture", 

640 {"mode": "survey", "layout": layout, "styles": list(styles)}, 

641 task=task, 

642 instruction_values={"mode": "survey", "styles": ", ".join(styles)}, 

643 instructions_suffix=reverse_engineering.SURVEY_SUFFIX if config.documents else "", 

644 validate=validate, 

645 ) 

646 if outcome.status is not ResultStatus.PASSED or outcome.result is None: 646 ↛ 647line 646 didn't jump to line 647 because the condition on line 646 was never true

647 return PhaseOutcome( 

648 ResultStatus.BLOCKED, 

649 f"The architecture survey did not answer ({outcome.status}): {outcome.summary}", 

650 outcome.evidence_refs, 

651 ) 

652 try: 

653 survey = validate(outcome.result) 

654 except ValueError as error: 

655 return self._malformed(execution, error, outcome.evidence_refs) 

656 return self._record_survey(execution, phase, config, outcome, survey, layout) 

657 

658 def _record_survey( 

659 self, 

660 execution: Execution, 

661 phase: PhaseExecution, 

662 config: ArchitectureSettings, 

663 outcome: AgentCallOutcome, 

664 survey: dict[str, Any], 

665 layout: list[str], 

666 ) -> PhaseOutcome | None: 

667 """Record a validated survey: the proposal, its documents and the event; a person 

668 approves the inferred rules unless there are none.""" 

669 rules = {"layers": survey["layers"], "allow": survey["allow"]} 

670 checked = self._checked(config, rules) 

671 digest = sha256_json({"style": survey["style"], **rules, **checked}) 

672 status = "PROPOSED" if survey["layers"] else "NONE" 

673 record = { 

674 "status": status, 

675 "mode": "survey", 

676 "style": survey["style"], 

677 "digest": digest, 

678 "rules": rules, 

679 **checked, 

680 "layout": layout, 

681 "layoutDigest": sha256_json(layout), 

682 "invocationId": outcome.invocation_id, 

683 "createdAt": utc_now().isoformat(), 

684 } 

685 ref = self.results.record_json( 

686 execution, 

687 PhaseId.DISCOVERY, 

688 {**record, "summary": survey["summary"]}, 

689 kind="architecture-survey", 

690 summary=f"Architecture survey: {survey['style']}, {len(survey['layers'])} layer(s)", 

691 ) 

692 (self.harness_dir / SURVEY_FILE).write_text( 

693 f"# Architecture of the project ({survey['style']})\n\n{survey['summary']}\n", 

694 encoding="utf-8", 

695 ) 

696 completed: dict[str, Any] = { 

697 "digest": digest, 

698 "status": status, 

699 "layers": len(survey["layers"]), 

700 "evidenceRef": ref, 

701 **({"baselineConflicts": len(checked["baselineConflicts"])} if checked else {}), 

702 } 

703 if survey.get("documentation") is not None: 

704 record["documentation"] = reverse_engineering.write_documents( 

705 self.harness_dir, survey, survey["documentation"], layout, digest=digest 

706 ) 

707 completed["documentation"] = record["documentation"]["digest"] 

708 self._write({**record, "ref": ref, "executionId": execution.execution_id}) 

709 self.results.s.events.append( 

710 execution.execution_id, 

711 "architecture.survey.completed", 

712 completed, 

713 phase_execution_id=phase.phase_execution_id, 

714 ) 

715 if status == "NONE": 

716 return None 

717 conflicts = conflicts_summary(record) 

718 return PhaseOutcome( 

719 ResultStatus.BLOCKED, 

720 f"The survey inferred {len(survey['layers'])} layer(s)" 

721 + (f" ({conflicts})" if conflicts else "") 

722 + ": a person approves the rules with harness architecture decide --run " 

723 f"{execution.execution_id} --decision APPROVE --digest {digest}", 

724 (ref,), 

725 ) 

726 

727 def _checked(self, config: ArchitectureSettings, rules: dict[str, Any]) -> dict[str, Any]: 

728 """Under ``baselineConflicts: allow`` (#93): the dependencies the baseline has and the 

729 inferred rules forbid, and the rules in force once a person approves. Empty without 

730 the key, so the proposal and its digest are the ones of the earlier behaviour.""" 

731 if not config.allows_baseline_conflicts or not rules["layers"]: 

732 return {} 

733 conflicts = baseline_conflicts(baseline_sources(self.results.s.paths.workspace), rules) 

734 return {"baselineConflicts": conflicts, "enforced": allowing(rules, conflicts)} 

735 

736 def _reused( 

737 self, 

738 execution: Execution, 

739 phase: PhaseExecution, 

740 config: ArchitectureSettings, 

741 state: dict[str, Any], 

742 layout: list[str], 

743 ) -> bool: 

744 """Whether the recorded survey still holds (recorded as reused): it is not stale and, 

745 under ``refresh: auto``, the source layout did not change materially.""" 

746 if state.get("stale"): 

747 return False 

748 refresh = (config.refresh or "manual") == "auto" 

749 if refresh and similarity(state.get("layout") or [], layout) < MATERIAL_CHANGE: 749 ↛ 750line 749 didn't jump to line 750 because the condition on line 749 was never true

750 return False 

751 if config.documents and not reverse_engineering.present( 

752 self.harness_dir, state.get("documentation") 

753 ): 

754 return False # the documents are missing: one survey writes them again 

755 reused: dict[str, Any] = { 

756 "digest": state.get("digest"), 

757 "status": state.get("status"), 

758 "layoutSimilarity": round(similarity(state.get("layout") or [], layout), 3), 

759 } 

760 if config.documents: 

761 reused["documentation"] = state["documentation"]["digest"] 

762 reused["agentCalls"] = 0 

763 self.results.s.events.append( 

764 execution.execution_id, 

765 "architecture.survey.reused", 

766 reused, 

767 phase_execution_id=phase.phase_execution_id, 

768 ) 

769 return True 

770 

771 def _malformed( 

772 self, execution: Execution, error: ValueError, refs: tuple[str, ...] 

773 ) -> PhaseOutcome: 

774 from governed_harness.domain.enums import FindingSeverity 

775 

776 self.results.record_finding( 

777 execution, 

778 validator_id="harness.architecture-call", 

779 rule_id="architecture.malformed", 

780 category="agent-protocol", 

781 severity=FindingSeverity.HIGH, 

782 message=f"The architecture call returned a malformed result: {error}", 

783 evidence_refs=refs, 

784 ) 

785 return PhaseOutcome( 

786 ResultStatus.BLOCKED, 

787 f"The architecture call returned a malformed result: {error}", 

788 refs, 

789 ) 

790 

791 # ----- decision (a person) --------------------------------------------------------------- 

792 def decide( 

793 self, 

794 execution: Execution, 

795 *, 

796 actor: Actor, 

797 digest: str, 

798 rationale: str, 

799 decision: DecisionKind | None = None, 

800 option: str | None = None, 

801 style: str | None = None, 

802 ) -> dict[str, Any]: 

803 if actor.actor_type is not ActorType.HUMAN: 803 ↛ 804line 803 didn't jump to line 804 because the condition on line 803 was never true

804 raise PolicyViolationError("only a person decides the architecture") 

805 state = self.state() 

806 if state is None or state.get("status") not in {"OPTIONS", "PROPOSED"}: 806 ↛ 807line 806 didn't jump to line 807 because the condition on line 806 was never true

807 raise NotFoundError("no architecture options or inferred rules wait for a decision") 

808 if state["digest"] != digest: 808 ↛ 809line 808 didn't jump to line 809 because the condition on line 808 was never true

809 raise PolicyViolationError("the digest does not match the architecture proposal") 

810 if not rationale.strip(): 810 ↛ 811line 810 didn't jump to line 811 because the condition on line 810 was never true

811 raise PolicyViolationError("a rationale is required") 

812 decided = { 

813 "decidedBy": actor.actor_id, 

814 "rationale": rationale, 

815 "decidedAt": utc_now().isoformat(), 

816 "decisionExecutionId": execution.execution_id, 

817 } 

818 updated: dict[str, Any] 

819 event: dict[str, Any] 

820 if state["status"] == "OPTIONS": 

821 chosen = self._chosen(state, option, style) 

822 adr = render_adr(chosen, decided_by=actor.actor_id, rationale=rationale, digest=digest) 

823 adr_ref = self.results.s.artifacts.put( 

824 adr.encode("utf-8"), 

825 media_type="text/markdown", 

826 metadata={"kind": "architecture-adr", "executionId": execution.execution_id}, 

827 ) 

828 target = self.harness_dir / ADR_FILE 

829 target.parent.mkdir(parents=True, exist_ok=True) 

830 target.write_text(adr, encoding="utf-8") 

831 updated = { 

832 **state, 

833 **decided, 

834 "status": "APPROVED", 

835 "style": chosen["style"], 

836 "option": chosen["id"], 

837 "rules": {"layers": chosen["layers"], "allow": chosen["allow"]}, 

838 "adrRef": adr_ref.uri, 

839 "adrDigest": adr_ref.digest, 

840 } 

841 event = { 

842 "decision": "CHOOSE", 

843 "option": chosen["id"], 

844 "digest": digest, 

845 "adrRef": adr_ref.uri, 

846 "adrDigest": adr_ref.digest, 

847 } 

848 if self.config is not None and self.config.experts: 

849 event["style"] = chosen["style"] 

850 event["acceptedRecommendation"] = bool(chosen.get("recommended")) 

851 updated["acceptedRecommendation"] = event["acceptedRecommendation"] 

852 self._write_style_doc(chosen["style"]) 

853 else: 

854 if decision not in {DecisionKind.APPROVE, DecisionKind.REJECT}: 854 ↛ 855line 854 didn't jump to line 855 because the condition on line 854 was never true

855 raise PolicyViolationError("inferred rules are approved or rejected") 

856 status = "APPROVED" if decision is DecisionKind.APPROVE else "REJECTED" 

857 updated = {**state, **decided, "status": status} 

858 event = {"decision": decision.value, "digest": digest} 

859 self._write(updated) 

860 self.results.s.events.append( 

861 execution.execution_id, "architecture.decided", event, actor=actor 

862 ) 

863 return updated 

864 

865 def _chosen( 

866 self, state: dict[str, Any], option: str | None, style: str | None 

867 ) -> dict[str, Any]: 

868 """The option a person chose: one of the proposed (``--option``) or, under 

869 ``catalogue: experts``, any style of the catalogue (``--style``; the proposed option of 

870 that style when there is one, else the style with its template rules).""" 

871 options: list[dict[str, Any]] = state["options"] 

872 if style is not None: 

873 return self._chosen_style(options, option, style) 

874 chosen = next((item for item in options if item["id"] == option), None) 

875 if option is None or chosen is None: 875 ↛ 876line 875 didn't jump to line 876 because the condition on line 875 was never true

876 known = ", ".join(item["id"] for item in options) 

877 raise PolicyViolationError(f"choose one option with --option ({known})") 

878 return chosen 

879 

880 def _chosen_style( 

881 self, options: list[dict[str, Any]], option: str | None, style: str 

882 ) -> dict[str, Any]: 

883 if option is not None: 

884 raise PolicyViolationError("choose with --option or with --style, not both") 

885 if self.config is None or not self.config.experts: 

886 raise PolicyViolationError("--style needs architecture.catalogue: experts") 

887 if not in_catalogue(style): 

888 raise PolicyViolationError( 

889 f"{style!r} is not a style of the catalogue ({', '.join(CATALOGUE_STYLES)})" 

890 ) 

891 proposed = next((item for item in options if item["style"] == style), None) 

892 return proposed or style_entry(style).as_option() 

893 

894 def _write_style_doc(self, style: str) -> None: 

895 """Copy the documentation of the chosen style into the project; requests point to it.""" 

896 if in_catalogue(style): 896 ↛ exitline 896 didn't return from function '_write_style_doc' because the condition on line 896 was always true

897 (self.harness_dir / STYLE_DOC_FILE).write_text( 

898 style_entry(style).document, encoding="utf-8" 

899 ) 

900 

901 def refresh(self) -> dict[str, Any]: 

902 state = self.state() 

903 if state is None: 

904 return {"status": "NONE", "note": "no survey cached; the next run surveys"} 

905 self._write({**state, "stale": True}) 

906 return {"status": "STALE", "note": "the next run surveys the project again"} 

907 

908 

909# ----- state file ----------------------------------------------------------------------------------- 

910def read_state(harness_dir: Path) -> dict[str, Any] | None: 

911 path = harness_dir / STATE_FILE 

912 try: 

913 value = json.loads(path.read_text(encoding="utf-8")) 

914 except (OSError, ValueError): 

915 return None 

916 return value if isinstance(value, dict) else None 

917 

918 

919def write_state(harness_dir: Path, value: dict[str, Any]) -> None: 

920 path = harness_dir / STATE_FILE 

921 path.parent.mkdir(parents=True, exist_ok=True) 

922 path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8") 

923 

924 

925def effective_rules(config: ArchitectureSettings | None, harness_dir: Path) -> LayerRules | None: 

926 """The layer rules in force: the configured layers, else the rules a person approved (from 

927 a survey or an ADR). ``None`` without an ``architecture`` section.""" 

928 if config is None: 

929 return None 

930 if config.layers: 930 ↛ 931line 930 didn't jump to line 931 because the condition on line 930 was never true

931 return LayerRules.from_mapping( 

932 [item.model_dump(mode="json", by_alias=True) for item in config.layers], 

933 {key: list(value) for key, value in (config.allow or {}).items()}, 

934 ) 

935 state = read_state(harness_dir) 

936 if state is None or state.get("status") != "APPROVED": 

937 return None 

938 # #93: the rules a person approved with the baseline's own dependencies allowed. 

939 rules = state.get("enforced") or state.get("rules") or {} 

940 return LayerRules.from_mapping(rules.get("layers") or [], rules.get("allow") or {}) 

941 

942 

943__all__ = [ 

944 "ADR_FILE", 

945 "MATERIAL_CHANGE", 

946 "STATE_FILE", 

947 "SURVEY_FILE", 

948 "ArchitectureFlow", 

949 "allowing", 

950 "baseline_conflicts", 

951 "baseline_sources", 

952 "conflicts_summary", 

953 "effective_rules", 

954 "read_state", 

955 "render_adr", 

956 "similarity", 

957 "source_layout", 

958 "validate_catalogue_options", 

959 "validate_documented_survey", 

960 "validate_options", 

961 "validate_organization", 

962 "validate_survey", 

963 "write_state", 

964]