Coverage for src/governed_harness/orchestration/reverse_engineering.py: 93%
67 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"""Reverse engineering of an existing project: persistent documents (wave 11, #97).
3The architecture survey of an existing project (DISCOVERY, once per project) already infers the
4style and the layer rules. Under ``architecture.documentation: project`` the same call also
5describes the components, the organisation of files and folders, the conventions and how the
6harness should act on the project, and the harness writes that as documents inside the project,
7``.harness/reverse-engineering``:
9* ``README.md``: the index, what each document is for and how to refresh them;
10* ``structure.md``: the source directories (listed by the harness, not by the agent), the
11 organisation the agent describes and the style;
12* ``components.md``: the main components, where they live and what each one is responsible for;
13* ``conventions.md``: the conventions the code shows (naming, tests, errors, configuration);
14* ``working-agreement.md``: how the harness and its agents act on the project from then on.
16Later requests carry a pointer to the directory and the working agreement, so an agent reads the
17documents on demand instead of analysing the project again. The survey is reused while the
18source layout holds (``architecture.survey.reused`` records each reuse with the digest of the
19documents) and runs again only on ``harness architecture refresh`` (or ``refresh: auto`` and a
20material change of the layout, or documents that are missing)."""
22from __future__ import annotations
24from pathlib import Path
25from typing import Any
27from governed_harness.evidence.hashing import sha256_bytes, sha256_json
29DIRECTORY = "reverse-engineering"
30INDEX = "README.md"
31AGREEMENT = "working-agreement.md"
32FILES = (INDEX, "structure.md", "components.md", "conventions.md", AGREEMENT)
33_MAX_COMPONENTS = 40
34_MAX_ITEMS = 30
35_MAX_TEXT = 20_000
36_MAX_AGREEMENT = 1500
38SURVEY_SUFFIX = (
39 " Besides the fields above the result needs the documentation of the project: "
40 '"organization" (Markdown: how files and folders are organised and where new code goes), '
41 '"components" (the main components: [{"name": "<name>", "path": "<path>", '
42 '"responsibility": "<one sentence>"}]), "conventions" (the conventions the code shows: '
43 'naming, tests, errors, configuration; a list of short sentences) and "guidance" (how an '
44 "agent must act on this project from now on: where to put code, what to run, what not to "
45 "touch; a list of short sentences). Base each on what you read; do not invent."
46)
47"""Added to the instructions of the survey under ``architecture.documentation: project``."""
50def _texts(value: Any, name: str, limit: int) -> list[str]:
51 if not isinstance(value, list):
52 raise ValueError(f"the survey needs a '{name}' list")
53 items = [str(item).strip()[:600] for item in value if str(item).strip()]
54 return items[:limit]
57def _component(item: Any) -> dict[str, str]:
58 if not isinstance(item, dict): 58 ↛ 59line 58 didn't jump to line 59 because the condition on line 58 was never true
59 raise ValueError("a component is an object")
60 fields = {key: str(item.get(key) or "").strip()[:400] for key in ("name", "path")}
61 fields["responsibility"] = str(item.get("responsibility") or "").strip()[:600]
62 if not fields["name"] or not fields["responsibility"]:
63 raise ValueError("every component needs a name and a responsibility")
64 if fields["path"].startswith("/") or ".." in fields["path"].split("/"):
65 raise ValueError(f"component {fields['name']}: the path must be relative")
66 return fields
69def validate_documentation(result: dict[str, Any]) -> dict[str, Any]:
70 """The documentation fields of a survey answer; a missing or empty part is an error, so a
71 survey cannot pass as documentation with nothing in it (fail closed)."""
72 organization = result.get("organization")
73 if not isinstance(organization, str) or not organization.strip():
74 raise ValueError("the survey needs an 'organization' text")
75 raw = result.get("components")
76 if not isinstance(raw, list) or not raw:
77 raise ValueError("the survey needs a non-empty 'components' list")
78 documentation = {
79 "organization": organization.strip()[:_MAX_TEXT],
80 "components": [_component(item) for item in raw[:_MAX_COMPONENTS]],
81 "conventions": _texts(result.get("conventions"), "conventions", _MAX_ITEMS),
82 "guidance": _texts(result.get("guidance"), "guidance", _MAX_ITEMS),
83 }
84 if not documentation["guidance"]:
85 raise ValueError("the survey needs a non-empty 'guidance' list")
86 return documentation
89def _bullets(items: list[str]) -> list[str]:
90 return [f"- {item}" for item in items] or ["- Nothing was recorded."]
93def _render(
94 survey: dict[str, Any], docs: dict[str, Any], layout: list[str], digest: str
95) -> dict[str, str]:
96 style = survey["style"]
97 stamp = f"Generated by the harness from the survey `{digest}`. Do not edit by hand."
98 components = [
99 f"- `{item['path'] or '.'}` **{item['name']}**: {item['responsibility']}"
100 for item in docs["components"]
101 ]
102 return {
103 INDEX: "\n".join(
104 [
105 "# Reverse engineering of the project",
106 "",
107 stamp,
108 "",
109 *[f"- `{name}`" for name in FILES[1:]],
110 "",
111 "The harness did this analysis once. Agents read these documents instead of "
112 + "analysing the project again. To redo it after the project changed materially, "
113 + "run `harness architecture refresh`: the next run surveys the project again "
114 + "and rewrites them.",
115 ]
116 ),
117 "structure.md": "\n".join(
118 [
119 f"# Structure ({style})",
120 "",
121 stamp,
122 "",
123 "## Source directories",
124 "",
125 *[f"- `{item}`" for item in layout],
126 "",
127 "## Organisation",
128 "",
129 docs["organization"],
130 "",
131 "## Architecture",
132 "",
133 survey["summary"],
134 ]
135 ),
136 "components.md": "\n".join(["# Main components", "", stamp, "", *components]),
137 "conventions.md": "\n".join(
138 ["# Conventions", "", stamp, "", *_bullets(docs["conventions"])]
139 ),
140 AGREEMENT: "\n".join(
141 [
142 "# How the harness acts on this project",
143 "",
144 stamp,
145 "",
146 *_bullets(docs["guidance"]),
147 "",
148 "- Read these documents before searching the code; do not analyse the whole "
149 + "project again.",
150 "- Respect the architecture rules the project approved; a change that needs "
151 + "another structure goes through a person.",
152 ]
153 ),
154 }
157def write_documents(
158 harness_dir: Path,
159 survey: dict[str, Any],
160 docs: dict[str, Any],
161 layout: list[str],
162 *,
163 digest: str,
164) -> dict[str, Any]:
165 """Write the documents; the record (digest of the set and of each file) goes in the state."""
166 target = harness_dir / DIRECTORY
167 target.mkdir(parents=True, exist_ok=True)
168 rendered = _render(survey, docs, layout, digest)
169 files: dict[str, str] = {}
170 for name, text in rendered.items():
171 body = text.rstrip() + "\n"
172 (target / name).write_text(body, encoding="utf-8")
173 files[name] = sha256_bytes(body.encode("utf-8"))
174 return {"directory": f".harness/{DIRECTORY}", "files": files, "digest": sha256_json(files)}
177def present(harness_dir: Path, record: Any) -> bool:
178 """Whether the documents of ``record`` are all in the project."""
179 if not isinstance(record, dict) or not isinstance(record.get("files"), dict): 179 ↛ 180line 179 didn't jump to line 180 because the condition on line 179 was never true
180 return False
181 return all((harness_dir / DIRECTORY / name).is_file() for name in record["files"])
184def request_block(harness_dir: Path, record: Any) -> dict[str, Any] | None:
185 """What the requests carry: where the documents are and the working agreement (short)."""
186 if not present(harness_dir, record): 186 ↛ 187line 186 didn't jump to line 187 because the condition on line 186 was never true
187 return None
188 agreement = (harness_dir / DIRECTORY / AGREEMENT).read_text(encoding="utf-8")
189 return {
190 "directory": f".harness/{DIRECTORY}",
191 "files": list(record["files"]),
192 "digest": record["digest"],
193 "workingAgreement": agreement[:_MAX_AGREEMENT],
194 }
197__all__ = [
198 "AGREEMENT",
199 "DIRECTORY",
200 "FILES",
201 "INDEX",
202 "SURVEY_SUFFIX",
203 "present",
204 "request_block",
205 "validate_documentation",
206 "write_documents",
207]