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
« 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).
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.
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.
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."""
31from __future__ import annotations
33import json
34from pathlib import Path
35from typing import TYPE_CHECKING, Any
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
65if TYPE_CHECKING:
66 from governed_harness.orchestration.hosts import ResultsHost
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
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)
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()
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)
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
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
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 ]
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}
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 )
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}
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
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})
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}
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
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
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
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 }
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
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"
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"])
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"
362# ----- the flow ---------------------------------------------------------------------------------------
363class ArchitectureFlow:
364 def __init__(self, results: ResultsHost) -> None:
365 self.results = results
367 @property
368 def config(self) -> ArchitectureSettings | None:
369 return self.results.project.architecture
371 @property
372 def harness_dir(self) -> Path:
373 return self.results.s.paths.harness_dir
375 def state(self) -> dict[str, Any] | None:
376 return read_state(self.harness_dir)
378 def _write(self, value: dict[str, Any]) -> None:
379 write_state(self.harness_dir, value)
381 def kind(self) -> ProjectKind:
382 return detect_project_kind(self.results.s.paths.workspace)
384 # ----- the rules in force ------------------------------------------------------------------
385 def rules(self) -> LayerRules | None:
386 return effective_rules(self.config, self.harness_dir)
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
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
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
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)
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 )
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})
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"],))
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
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)
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 )
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)}
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
771 def _malformed(
772 self, execution: Execution, error: ValueError, refs: tuple[str, ...]
773 ) -> PhaseOutcome:
774 from governed_harness.domain.enums import FindingSeverity
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 )
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
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
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()
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 )
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"}
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
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")
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 {})
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]