Coverage for src/governed_harness/agents/context_manifest.py: 99%

147 statements  

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

1"""A bounded, deterministic context manifest for the agent (issue #41). 

2 

3Agents spend much of a run discovering which files matter. The manifest gives them a short, 

4ranked starting list chosen only from the task and the workspace (paths the task names, the 

5declared interfaces, files changed by earlier steps, requirement ids and key terms), so the same 

6task and workspace always give the same manifest and its digest can be recorded as evidence. 

7 

8The manifest is guidance, never a restriction: the agent may still read any file of the 

9workspace, and the sandbox, not this list, decides what it can touch. 

10""" 

11 

12from __future__ import annotations 

13 

14import os 

15import re 

16from collections import Counter 

17from collections.abc import Collection, Iterator, Mapping, Sequence 

18from pathlib import Path, PurePosixPath 

19from typing import Any 

20 

21from governed_harness.domain.models import Task 

22from governed_harness.evidence.hashing import sha256_bytes, sha256_json 

23from governed_harness.runtime.workspace import DEFAULT_EXCLUDES 

24 

25__all__ = [ 

26 "GUIDANCE", 

27 "MAX_FILE_BYTES", 

28 "build_manifest", 

29 "key_terms", 

30 "referenced_paths", 

31] 

32 

33GUIDANCE = ( 

34 "Start from these files; they were chosen deterministically from the task. " 

35 "You may read any other file of the workspace." 

36) 

37MAX_FILE_BYTES = 1024 * 1024 

38"""Files larger than this are never candidates: they are usually generated or data files.""" 

39 

40_BINARY_PROBE = 8192 

41_WORD = re.compile(r"\w+", re.ASCII) 

42_PATH_TOKEN = re.compile(r"[A-Za-z0-9_./\-]+") 

43_STOPWORDS: frozenset[str] = frozenset( 

44 { 

45 "about", 

46 "above", 

47 "after", 

48 "again", 

49 "against", 

50 "always", 

51 "among", 

52 "before", 

53 "being", 

54 "below", 

55 "between", 

56 "could", 

57 "doing", 

58 "during", 

59 "every", 

60 "first", 

61 "given", 

62 "having", 

63 "might", 

64 "never", 

65 "other", 

66 "should", 

67 "second", 

68 "shall", 

69 "since", 

70 "their", 

71 "there", 

72 "these", 

73 "third", 

74 "those", 

75 "through", 

76 "under", 

77 "until", 

78 "using", 

79 "value", 

80 "values", 

81 "where", 

82 "which", 

83 "while", 

84 "within", 

85 "without", 

86 "would", 

87 "return", 

88 "returns", 

89 "must", 

90 } 

91) 

92 

93 

94def _words(text: str) -> list[str]: 

95 return [word.lower() for word in _WORD.findall(text)] 

96 

97 

98def key_terms(task: Task, limit: int = 12) -> tuple[str, ...]: 

99 """The most frequent meaningful words of the task's title, requirements and criteria. 

100 

101 Short words and common English words carry no signal about which files matter, so they 

102 are dropped; ties are broken alphabetically to keep the result deterministic. 

103 """ 

104 texts = [task.title] 

105 texts += [requirement.text for requirement in task.requirements] 

106 texts += [criterion.text for criterion in task.acceptance_criteria] 

107 counts: Counter[str] = Counter( 

108 word for text in texts for word in _words(text) if len(word) >= 5 and word not in _STOPWORDS 

109 ) 

110 ranked = sorted(counts.items(), key=lambda item: (-item[1], item[0])) 

111 return tuple(word for word, _count in ranked[:limit]) 

112 

113 

114def _strings(value: Any) -> Iterator[str]: 

115 if isinstance(value, str): 

116 yield value 

117 elif isinstance(value, Mapping): 

118 for item in value.values(): 

119 yield from _strings(item) 

120 elif isinstance(value, (list, tuple)): 

121 for item in value: 

122 yield from _strings(item) 

123 

124 

125def _task_texts(task: Task) -> list[str]: 

126 texts = [task.intent, *task.constraints] 

127 texts += [requirement.text for requirement in task.requirements] 

128 for criterion in task.acceptance_criteria: 

129 texts.append(criterion.text) 

130 if criterion.verification_hint: 

131 texts.append(criterion.verification_hint) 

132 texts += list(_strings(task.metadata)) 

133 return texts 

134 

135 

136def _normalise(path: str) -> str: 

137 """A workspace-relative POSIX path without a leading ``./``.""" 

138 cleaned = path.replace("\\", "/") 

139 while cleaned.startswith("./"): 

140 cleaned = cleaned[2:] 

141 return cleaned 

142 

143 

144def _inside(root: Path, relative: str) -> bool: 

145 if not relative or relative.startswith("/") or PurePosixPath(relative).is_absolute(): 

146 return False 

147 if ".." in PurePosixPath(relative).parts: 

148 return False 

149 try: 

150 resolved = (root / relative).resolve() 

151 resolved.relative_to(root) 

152 except (OSError, ValueError): 

153 return False 

154 return resolved.is_file() 

155 

156 

157def referenced_paths(task: Task, workspace: Path) -> tuple[str, ...]: 

158 """Workspace files the task mentions by path. 

159 

160 Only paths that stay inside the workspace count: a ``../`` or absolute path in the task is 

161 ignored rather than followed, so the manifest can never point outside the root. 

162 """ 

163 root = workspace.resolve() 

164 found: set[str] = set() 

165 for text in _task_texts(task): 

166 for token in _PATH_TOKEN.findall(text): 

167 candidate = _normalise(token.rstrip(".-").lstrip("-")) 

168 if "/" not in candidate and "." not in candidate: 

169 continue 

170 if _inside(root, candidate): 

171 found.add(candidate) 

172 return tuple(sorted(found)) 

173 

174 

175def _walk(root: Path, excludes: Collection[str]) -> Iterator[tuple[str, Path]]: 

176 """Regular files of the workspace in sorted order, without excluded dirs or symlinks.""" 

177 for directory, dirnames, filenames in os.walk(root, followlinks=False): 

178 base = Path(directory) 

179 dirnames[:] = [ 

180 name 

181 for name in sorted(dirnames) 

182 if name not in excludes and not (base / name).is_symlink() 

183 ] 

184 for name in sorted(filenames): 

185 path = base / name 

186 if path.is_symlink() or not path.is_file(): 

187 continue 

188 yield path.relative_to(root).as_posix(), path 

189 

190 

191def _read_text(path: Path) -> bytes | None: 

192 try: 

193 if path.stat().st_size > MAX_FILE_BYTES: 

194 return None 

195 data = path.read_bytes() 

196 except OSError: 

197 return None 

198 if b"\x00" in data[:_BINARY_PROBE]: 

199 return None 

200 return data 

201 

202 

203def _id_pattern(identifier: str) -> re.Pattern[str]: 

204 return re.compile(rf"(?<!\w){re.escape(identifier)}(?!\w)") 

205 

206 

207def _score( 

208 relative: str, 

209 content: str, 

210 *, 

211 referenced: set[str], 

212 interfaces: set[str], 

213 changed: set[str], 

214 lessons: set[str], 

215 id_patterns: Sequence[tuple[str, re.Pattern[str]]], 

216 terms: Sequence[str], 

217 located: set[str] | None = None, 

218) -> tuple[int, list[str]]: 

219 score = 0 

220 reasons: list[str] = [] 

221 for paths, points, reason in ( 

222 (referenced, 100, "referenced by the task"), 

223 (located or set(), 80, "located by the locate call"), 

224 (interfaces, 60, "declared interface"), 

225 (changed, 50, "changed by an earlier step"), 

226 (lessons, 20, "path of an active lesson"), 

227 ): 

228 if relative in paths: 

229 score += points 

230 reasons.append(reason) 

231 

232 named = [identifier for identifier, pattern in id_patterns if pattern.search(content)] 

233 if named: 

234 score += min(40 + 5 * (len(named) - 1), 60) 

235 reasons.append(f"names {', '.join(named[:5])}") 

236 if "test" in relative.lower(): 

237 score += 10 

238 reasons.append("test naming a requirement") 

239 

240 lowered_path = relative.lower() 

241 in_path = [term for term in terms if term in lowered_path] 

242 if in_path: 

243 score += min(10 * len(in_path), 30) 

244 reasons.extend(f"path mentions {term}" for term in in_path[:3]) 

245 

246 content_words = set(_words(content)) 

247 in_content = [term for term in terms if term in content_words] 

248 if in_content: 

249 score += min(2 * len(in_content), 20) 

250 reasons.append(f"mentions {len(in_content)} key term(s)") 

251 return score, reasons 

252 

253 

254def build_manifest( 

255 workspace: Path, 

256 task: Task, 

257 *, 

258 changed_paths: Sequence[str] = (), 

259 interface_paths: Sequence[str] = (), 

260 lesson_paths: Sequence[str] = (), 

261 located_paths: Sequence[str] = (), 

262 max_files: int = 40, 

263 max_bytes: int = 400_000, 

264 excludes: Collection[str] = DEFAULT_EXCLUDES, 

265) -> dict[str, Any]: 

266 """Rank the workspace files by relevance to the task and keep the best within the limits. 

267 

268 A file that would exceed ``max_bytes`` is skipped and the next one is tried, so one large 

269 file does not crowd out several small relevant ones. 

270 """ 

271 root = workspace.resolve() 

272 terms = key_terms(task) 

273 identifiers = list( 

274 dict.fromkeys( 

275 [requirement.requirement_id for requirement in task.requirements] 

276 + [criterion.criterion_id for criterion in task.acceptance_criteria] 

277 ) 

278 ) 

279 id_patterns = [(identifier, _id_pattern(identifier)) for identifier in identifiers] 

280 referenced = set(referenced_paths(task, root)) 

281 interfaces = {_normalise(path) for path in interface_paths} 

282 changed = {_normalise(path) for path in changed_paths} 

283 lessons = {_normalise(path) for path in lesson_paths} 

284 located = {_normalise(path) for path in located_paths} 

285 

286 candidates: list[tuple[int, str, int, str, list[str]]] = [] 

287 for relative, path in _walk(root, excludes): 

288 data = _read_text(path) 

289 if data is None: 

290 continue 

291 score, reasons = _score( 

292 relative, 

293 data.decode("utf-8", errors="replace"), 

294 referenced=referenced, 

295 interfaces=interfaces, 

296 changed=changed, 

297 lessons=lessons, 

298 id_patterns=id_patterns, 

299 terms=terms, 

300 located=located, 

301 ) 

302 if score > 0: 

303 candidates.append((score, relative, len(data), sha256_bytes(data), reasons)) 

304 candidates.sort(key=lambda item: (-item[0], item[1])) 

305 

306 files: list[dict[str, Any]] = [] 

307 total = 0 

308 for score, relative, size, digest, reasons in candidates: 

309 if len(files) >= max_files: 

310 break 

311 if total + size > max_bytes: 

312 continue 

313 total += size 

314 files.append( 

315 { 

316 "path": relative, 

317 "sizeBytes": size, 

318 "digest": digest, 

319 "score": score, 

320 "reasons": reasons, 

321 } 

322 ) 

323 return { 

324 "schemaVersion": "1.0", 

325 "files": files, 

326 "terms": list(terms), 

327 "limits": {"maxFiles": max_files, "maxBytes": max_bytes}, 

328 "candidates": len(candidates), 

329 "omitted": len(candidates) - len(files), 

330 "totalBytes": total, 

331 "guidance": GUIDANCE, 

332 "digest": sha256_json({"files": files, "terms": list(terms)}), 

333 }