Coverage for src/governed_harness/agents/requests.py: 97%
29 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"""Kinds of agent request and the instructions the harness renders for each (#37).
3Before 1.1 the provider protocol had one request: implement the task. The agent-results
4settings add three more kinds that ask a provider for structured judgement the deterministic
5rules cannot give:
7* ``clarify`` (INTENT): ambiguity and completeness questions about the task;
8* ``review`` (INDEPENDENT_REVIEW): findings of a second reviewer on the ChangeSet;
9* ``plan`` (PLANNING): ordered sub-tasks that partition the task's requirements;
10* ``acceptance`` (SPECIFICATION): acceptance tests written from the criteria by a separate
11 call, returned as files that the harness writes and freezes once a person approves them;
12* ``locate`` (INTENT, since #55): where to intervene, as ``path:line`` with evidence, for a
13 task the router classifies M or L; ambiguous places come back as questions.
14* ``architecture`` (since #56; INTENT for a new project, DISCOVERY for an existing one): one
15 call per project that either surveys the patterns in use (``mode: survey``) or proposes
16 architecture options with trade-offs (``mode: advise``); a person approves or chooses.
18These kinds are read-only by contract: the request says so (``readOnly: true``) and the harness
19compares the workspace before and after the call; a provider that changed it gets a HIGH
20finding, its changes are undone and its answer is discarded (under ``runtime.contractRetry``
21the call is then sent once more, #92). The agent proposes; only a person
22answers clarification questions and approves a plan.
24The response of every kind is the JSON object of the 1.0 protocol (``status``, ``summary``,
25optional ``usage``); the non-implement kinds add ``result`` with their structured answer."""
27from __future__ import annotations
29from typing import Any, Final, Literal
31CallKind = Literal["implement", "clarify", "review", "plan", "acceptance", "architecture", "locate"]
33CALL_KINDS: Final[tuple[CallKind, ...]] = (
34 "implement",
35 "clarify",
36 "review",
37 "plan",
38 "acceptance",
39 "architecture",
40 "locate",
41)
42READ_ONLY_KINDS: Final[frozenset[str]] = frozenset(
43 {"clarify", "review", "plan", "acceptance", "architecture", "locate"}
44)
45REQUEST_SCHEMA_VERSION = "1.1"
46"""Version of a request that carries ``kind`` and ``instructions``; an implement request sent
47without any agent-results key keeps the 1.0 form (and its prompt digest)."""
49CLARIFY_CATEGORIES: Final[tuple[str, ...]] = (
50 "ambiguity",
51 "contradiction",
52 "boundaries",
53 "errors",
54 "missing-flows",
55 "actors-and-roles",
56 "data-and-states",
57 "edge-cases",
58 "non-functional",
59 "integrations",
60 "acceptance-evidence",
61 "out-of-scope",
62 "consistency",
63)
64"""Categories of an agent's clarification questions (#37: ambiguity and completeness)."""
66REVIEW_SEVERITIES: Final[tuple[str, ...]] = ("INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL")
68_READ_ONLY = (
69 "This request is read-only: do not create, modify or delete any file and do not run "
70 "commands that change the workspace. The harness compares the workspace before and after "
71 "the call and discards the answer of a call that changed it."
72)
74_JSON = (
75 "Print exactly one JSON object on standard output: "
76 '{{"status": "PASSED", "summary": "<one sentence>", "result": RESULT}}. '
77 'Use "status": "BLOCKED" with a summary when you cannot answer.'
78)
80INSTRUCTIONS: Final[dict[CallKind, str]] = {
81 "implement": (
82 "Implement the task in the workspace at {workspace}: satisfy every requirement and "
83 "acceptance criterion and respect every constraint. Work only inside the workspace. "
84 "The gate below lists the validators and review rules the harness will run on your "
85 "ChangeSet; run the check command before you finish and fix what it reports. Do not "
86 "weaken tests, thresholds or checks to make them pass. Report honestly: print "
87 '{{"status": "PASSED"|"FAILED"|"BLOCKED", "summary": "<what you did>"}}.'
88 ),
89 "clarify": (
90 "Review the task below before any work starts. Read the task and the files it "
91 "references in the workspace at {workspace}. Ask concrete, answerable questions, each "
92 "in one category of: {categories}. Look for ambiguities, contradictions, undefined "
93 "boundaries and error precedences, and for completeness: missing features or flows the "
94 "intent implies, actors and roles, data and states, edge cases and error handling, "
95 "non-functional requirements (performance, security, persistence, accessibility, "
96 "observability), integrations and constraints, the acceptance evidence of each "
97 "requirement, and what is explicitly out of scope. Do not repeat the questions listed "
98 "in deterministicQuestions. When answers are listed in clarifications, check each one "
99 "against the documents it references and against the other answers, and ask about any "
100 "contradiction or wrong example (category consistency). Ask nothing when the task is "
101 "complete and unambiguous. "
102 + _READ_ONLY
103 + " "
104 + _JSON.replace(
105 "RESULT",
106 '{{"questions": [{{"category": "<category>", "target": "task" or a criterion id, '
107 '"text": "<question>"}}]}}',
108 )
109 ),
110 "review": (
111 "You are an independent reviewer. Compare the ChangeSet (the unified diff below, applied "
112 "to the workspace at {workspace}) with the task's requirements, acceptance criteria and "
113 "constraints. Report defects that tests, linters and type checkers do not see: wrong "
114 "formulas or rules, broken public signatures, unsafe deserialization, stored card data "
115 "or secrets, missing error handling, requirements not implemented. Each finding needs a "
116 "severity (INFO, LOW, MEDIUM, HIGH, CRITICAL), a short rule id, the file and line, a "
117 "message and the evidence (the code or requirement it is about). HIGH and CRITICAL "
118 "block the delivery: use them only for defects you can show. "
119 + _READ_ONLY
120 + " "
121 + _JSON.replace(
122 "RESULT",
123 '{{"findings": [{{"severity": "HIGH", "rule": "<rule>", "path": "<file>", '
124 '"line": 1, "message": "<message>", "evidence": "<evidence>"}}]}}',
125 )
126 ),
127 "plan": (
128 "Split the task below into ordered sub-tasks that can each be implemented and verified "
129 "on their own, in the workspace at {workspace}. The sub-tasks must partition the "
130 "requirements: every requirement id appears in exactly one sub-task. Give each "
131 "sub-task a title, its requirement ids, the acceptance criterion ids it satisfies "
132 "and the constraints that apply to it; cross-cutting constraints are added to every "
133 "sub-task by the harness. At most {maxSubtasks} sub-tasks. "
134 + _READ_ONLY
135 + " "
136 + _JSON.replace(
137 "RESULT",
138 '{{"subtasks": [{{"title": "<title>", "requirements": ["<id>"], '
139 '"criteria": ["<id>"], "constraints": ["<text>"]}}]}}',
140 )
141 ),
142 "acceptance": (
143 "Write acceptance tests for the task below from its acceptance criteria and "
144 "requirements only, before any implementation exists, for the workspace at "
145 "{workspace}. Use pytest; put every file under {directory}/ with a name that starts "
146 "with test_; name each test after the criterion or requirement id it checks. Test the "
147 "observable behaviour the criteria describe, including at least one end-to-end flow; "
148 "do not test implementation details. The tests must fail on the current workspace and "
149 "pass once the task is implemented. Return the files instead of writing them: the "
150 "harness writes them after a person approves them, and then freezes them. "
151 + _READ_ONLY
152 + " "
153 + _JSON.replace(
154 "RESULT",
155 '{{"tests": [{{"path": "{directory}/test_<name>.py", "content": "<file>"}}]}}',
156 )
157 ),
158 "locate": (
159 "Find where the task below must be implemented in the workspace at {workspace}, before "
160 "anyone changes it. Read the files the task references and search the code for its "
161 "requirements and criteria. Return at most {maxLocations} locations, most relevant "
162 "first, each with the file, the line, the evidence (the code or text that shows it is "
163 "the place) and why it must change. When the task could be implemented in clearly "
164 "different places and the task does not say which, ask instead of guessing. "
165 + _READ_ONLY
166 + " "
167 + _JSON.replace(
168 "RESULT",
169 '{{"locations": [{{"path": "<file>", "line": 1, "evidence": "<code>", '
170 '"reason": "<why>"}}], "questions": [{{"text": "<question>"}}]}}',
171 )
172 ),
173}
176ARCHITECTURE_INSTRUCTIONS: Final[dict[str, str]] = {
177 "survey": (
178 "Survey the architecture of the existing project in the workspace at {workspace}, once: "
179 "read the directory layout (layout below) and a few representative files, not the whole "
180 "code base. Describe the patterns in use (style, layers or modules and the direction of "
181 "their dependencies, naming and testing conventions) in short Markdown, and infer the "
182 "layer rules a tool can enforce: each layer with path globs and/or dotted module "
183 "prefixes, and the layers each layer may depend on. Infer only what the code shows; "
184 "return no layers when no layering is visible. The style is one of: {styles}. "
185 + _READ_ONLY
186 + " "
187 + _JSON.replace(
188 "RESULT",
189 '{{"style": "<style>", "summary": "<markdown>", "layers": [{{"name": "<layer>", '
190 '"paths": ["<glob>"], "modules": ["<prefix>"]}}], "allow": {{"<layer>": '
191 '["<layer>"]}}}}',
192 )
193 ),
194 "advise": (
195 "The project in the workspace at {workspace} is new. From the task below and the "
196 "project's scaffolding, propose two to four architecture options, each one of: "
197 "{styles}. Give each option an id, its style, a title, its trade-offs (benefits, costs, "
198 "when it fits this task and team), the layers with path globs and/or dotted module "
199 "prefixes, and the layers each layer may depend on. Mark exactly one as recommended. "
200 "A person chooses; the harness records the choice as an ADR and enforces its layers. "
201 + _READ_ONLY
202 + " "
203 + _JSON.replace(
204 "RESULT",
205 '{{"options": [{{"id": "<id>", "style": "<style>", "title": "<title>", '
206 '"benefits": ["<text>"], "costs": ["<text>"], "fit": "<text>", "recommended": true, '
207 '"layers": [{{"name": "<layer>", "paths": ["<glob>"], "modules": ["<prefix>"]}}], '
208 '"allow": {{"<layer>": ["<layer>"]}}}}]}}',
209 )
210 ),
211 "organize": (
212 "A person chose the {style} architecture for the new project in the workspace at "
213 "{workspace}. You are the expert for that style (your guidance follows). From the task "
214 "below and the chosen layer rules, plan how the project is organised: the directories "
215 "and modules with their purpose, and the best practices of the style that apply. The "
216 "implementation follows your plan, so name concrete relative paths. "
217 + _READ_ONLY
218 + " "
219 + _JSON.replace(
220 "RESULT",
221 '{{"summary": "<markdown>", "structure": [{{"path": "<relative path>", '
222 '"purpose": "<text>"}}], "practices": ["<text>"]}}',
223 )
224 ),
225}
226"""Instructions of the ``architecture`` call by its mode (#56, ``organize`` since #97)."""
228ADVISE_CATALOGUE_SUFFIX: Final[str] = (
229 "Offer only styles of the catalogue in the request (each one with what it is for and when "
230 "it fits). Besides the fields above, give every option a 'fit' that explains why it suits "
231 "this project and a 'supports' list with the characteristics of the project, from the task "
232 "and its scaffolding, that make it suitable. Mark exactly one option as recommended: a "
233 "person reads your report, then accepts it or chooses another style."
234)
235"""Added to the instructions of the advise call under ``architecture.catalogue: experts``."""
237ACCEPTANCE_GHERKIN: Final[str] = (
238 "Write the acceptance criteria and requirements of the task below as Gherkin feature files "
239 "(behaviour-driven development), before any implementation exists, for the workspace at "
240 "{workspace}. Put every file under {directory}/ with the .feature extension; each Scenario "
241 "names the criterion or requirement id it covers and uses Given, When, Then steps that "
242 "state observable behaviour, not implementation details. Write no step definitions: a "
243 "person approves the scenarios, the harness freezes them, and the implementation then "
244 "writes the step definitions and the code. "
245 + _READ_ONLY
246 + " "
247 + _JSON.replace(
248 "RESULT",
249 '{{"tests": [{{"path": "{directory}/<name>.feature", "content": "<Feature: ...>"}}]}}',
250 )
251)
252"""Instructions of the ``acceptance`` call under ``testing.strategy: bdd`` (#56)."""
255def render_instructions(kind: CallKind, *, workspace: str, **values: Any) -> str:
256 """The instructions of a request kind with its placeholders filled."""
257 fields: dict[str, Any] = {
258 "workspace": workspace,
259 "categories": ", ".join(CLARIFY_CATEGORIES),
260 "maxSubtasks": 12,
261 "directory": "tests/acceptance",
262 "maxLocations": 20,
263 "styles": "",
264 "style": "",
265 }
266 fields.update(values)
267 if kind == "acceptance" and fields.get("format") == "gherkin":
268 return ACCEPTANCE_GHERKIN.format(**fields)
269 if kind == "architecture":
270 return ARCHITECTURE_INSTRUCTIONS[str(fields.get("mode") or "survey")].format(**fields)
271 return INSTRUCTIONS[kind].format(**fields)
274def phase_of(kind: CallKind) -> str:
275 """The phase a call kind belongs to."""
276 return {
277 "implement": "IMPLEMENTATION",
278 "clarify": "INTENT",
279 "review": "INDEPENDENT_REVIEW",
280 "plan": "PLANNING",
281 "acceptance": "SPECIFICATION",
282 "locate": "INTENT",
283 "architecture": "DISCOVERY",
284 }[kind]