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

1"""Kinds of agent request and the instructions the harness renders for each (#37). 

2 

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: 

6 

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. 

17 

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. 

23 

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

26 

27from __future__ import annotations 

28 

29from typing import Any, Final, Literal 

30 

31CallKind = Literal["implement", "clarify", "review", "plan", "acceptance", "architecture", "locate"] 

32 

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

48 

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

65 

66REVIEW_SEVERITIES: Final[tuple[str, ...]] = ("INFO", "LOW", "MEDIUM", "HIGH", "CRITICAL") 

67 

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) 

73 

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) 

79 

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} 

174 

175 

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

227 

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

236 

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

253 

254 

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) 

272 

273 

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]