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

1"""Reverse engineering of an existing project: persistent documents (wave 11, #97). 

2 

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``: 

8 

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. 

15 

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

21 

22from __future__ import annotations 

23 

24from pathlib import Path 

25from typing import Any 

26 

27from governed_harness.evidence.hashing import sha256_bytes, sha256_json 

28 

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 

37 

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

48 

49 

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] 

55 

56 

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 

67 

68 

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 

87 

88 

89def _bullets(items: list[str]) -> list[str]: 

90 return [f"- {item}" for item in items] or ["- Nothing was recorded."] 

91 

92 

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 } 

155 

156 

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)} 

175 

176 

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

182 

183 

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 } 

195 

196 

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]