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
« 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).
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.
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"""
12from __future__ import annotations
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
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
25__all__ = [
26 "GUIDANCE",
27 "MAX_FILE_BYTES",
28 "build_manifest",
29 "key_terms",
30 "referenced_paths",
31]
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."""
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)
94def _words(text: str) -> list[str]:
95 return [word.lower() for word in _WORD.findall(text)]
98def key_terms(task: Task, limit: int = 12) -> tuple[str, ...]:
99 """The most frequent meaningful words of the task's title, requirements and criteria.
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])
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)
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
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
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()
157def referenced_paths(task: Task, workspace: Path) -> tuple[str, ...]:
158 """Workspace files the task mentions by path.
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))
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
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
203def _id_pattern(identifier: str) -> re.Pattern[str]:
204 return re.compile(rf"(?<!\w){re.escape(identifier)}(?!\w)")
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)
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")
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])
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
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.
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}
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]))
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 }