Coverage for src/governed_harness/intake/clarification.py: 97%

337 statements  

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

1"""Deterministic assessment of a task's intent before any work starts. 

2 

3INTENT checks that a task is structurally complete; this module checks that its acceptance 

4criteria say something that can be observed. It uses fixed vocabularies and patterns, no 

5language model, so the same task always yields the same questions with the same ids. 

6 

7The rules are deliberately conservative: a criterion is questioned only when nothing in it 

8(or in its verification hint) can be checked, so a false question is rarer than a missed one. 

9 

10* ``C0`` no acceptance criteria: a task accepted without criteria (``criteria_pending``, only 

11 under the ``enforce`` policy) gets one question per thing its criteria must settle, in a 

12 fixed order: results and how each is checked, inputs and outputs, limits, errors, behaviours 

13 in scope, what is out of scope and non-functional constraints. ``C0`` subsumes ``T1``. 

14* ``C1`` no observable result: fewer than four words, or only vague vocabulary, and no anchor. 

15* ``C2`` quality without a measure: a quality word such as "fast" or "secure" and no number. 

16* ``C3`` duplicate: the same criterion text (and hint) as an earlier criterion. 

17* ``T1`` scope without breakdown: an intent under 25 words, no requirements and a single 

18 criterion that has no anchor. 

19 

20An anchor is a digit, quoted or back-quoted text, a code identifier (``name()``, a 

21``snake_case`` name, a path, a file name, a ``CamelCase`` name such as ``ValueError``) or a 

22checkable result verb (returns, raises, rejects, ...). 

23 

24Since 2.0, ``intake.language`` (``auto``, ``en`` or ``es``, see :mod:`.language`) makes the 

25words Unicode tokens, adds the Spanish vocabularies under ``es`` and asks the questions in 

26Spanish. Without the key (``language=None``) the rules are the ones above, unchanged. 

27""" 

28 

29from __future__ import annotations 

30 

31import re 

32from collections.abc import Callable 

33from dataclasses import dataclass, field 

34from typing import Any 

35 

36from governed_harness.domain.errors import ConfigurationError 

37from governed_harness.domain.ids import new_id 

38from governed_harness.domain.models import ( 

39 AcceptanceCriterion, 

40 ClarificationQuestion, 

41 ClarificationRule, 

42 Requirement, 

43 Task, 

44) 

45from governed_harness.evidence import sha256_json 

46 

47from . import depth 

48from . import language as lang 

49 

50QUESTION_TEMPLATES: dict[str, str] = { 

51 "C0a": ( 

52 "Task '{title}' has no acceptance criteria. Which observable results show that it is " 

53 "done, and how is each one checked (input or action -> exact expected result)? One " 

54 "result per line." 

55 ), 

56 "C0b": ( 

57 "What are the main inputs and outputs of task '{title}', and in which formats (for " 

58 "example JSON fields, a CSV header or a function signature)?" 

59 ), 

60 "C0c": ( 

61 "Which limits and boundaries must task '{title}' respect (numbers, sizes, times), and " 

62 "what happens exactly at each boundary?" 

63 ), 

64 "C0d": ( 

65 "Which errors or rejections should task '{title}' produce for invalid input, and what " 

66 "exactly does each one return, raise or print?" 

67 ), 

68 "C0e": "Which behaviours are in scope for task '{title}'? One behaviour per line.", 

69 "C0f": "What is explicitly out of scope for task '{title}'? One item per line.", 

70 "C0g": ( 

71 "Which non-functional constraints apply to task '{title}' (performance, security, " 

72 "persistence), and with which measure is each one checked?" 

73 ), 

74 "C1": ( 

75 "Criterion {target} ('{text}') does not say what can be observed. For which input or " 

76 "action, and what exact result shows that it holds?" 

77 ), 

78 "C2": ( 

79 "Criterion {target} ('{text}') asks for a quality ('{term}') without a measure. What " 

80 "number or threshold decides whether it holds (for example a time, a size or a rate)?" 

81 ), 

82 "C3": ( 

83 "Criterion {target} ('{text}') repeats criterion {other}. What different result should " 

84 "it check, or which criterion should replace it?" 

85 ), 

86 "T1": ( 

87 "The intent ('{text}') is short, has no requirements and a single acceptance criterion " 

88 "with nothing concrete to check. Which separate behaviours must the task deliver, and " 

89 "what is out of scope?" 

90 ), 

91} 

92"""English question templates, one per rule and, for ``C0``, one per elicitation question 

93(``C0a`` to ``C0g``). The only place where question texts live.""" 

94 

95TASK_TARGET = "task" 

96"""Target of a question about the task as a whole rather than one criterion.""" 

97 

98C0_TARGETS: tuple[str, ...] = ( 

99 "task:results", 

100 "task:interface", 

101 "task:limits", 

102 "task:errors", 

103 "task:scope", 

104 "task:out-of-scope", 

105 "task:non-functional", 

106) 

107"""Targets of the ``C0`` questions, in the order they are asked (templates ``C0a`` to ``C0g``). 

108 

109Each names the part of the task its answer lands in when the task is revised.""" 

110 

111OUT_OF_SCOPE_PREFIX = "Out of scope: " 

112"""Prefix of the constraints made from the answer about what is out of scope.""" 

113 

114_C0_TEMPLATE_KEYS = tuple(f"C0{letter}" for letter in "abcdefg") 

115 

116MIN_CRITERION_WORDS = 4 

117MIN_INTENT_WORDS = 25 

118_EXCERPT = 120 

119 

120_VAGUE_PHRASES = ("as expected", "user-friendly", "user friendly") 

121_VAGUE_WORDS = frozenset( 

122 { 

123 "work", 

124 "works", 

125 "worked", 

126 "working", 

127 "correctly", 

128 "properly", 

129 "good", 

130 "fine", 

131 "nice", 

132 "clean", 

133 "robust", 

134 "well", 

135 } 

136) 

137# Words that carry no observable content of their own: articles, auxiliaries, connectors 

138# and the generic nouns people use for "the thing being built". 

139_FILLER_WORDS = frozenset( 

140 { 

141 "a", 

142 "an", 

143 "the", 

144 "it", 

145 "its", 

146 "this", 

147 "that", 

148 "these", 

149 "those", 

150 "everything", 

151 "all", 

152 "should", 

153 "must", 

154 "will", 

155 "shall", 

156 "can", 

157 "be", 

158 "is", 

159 "are", 

160 "was", 

161 "were", 

162 "been", 

163 "being", 

164 "has", 

165 "have", 

166 "and", 

167 "or", 

168 "but", 

169 "also", 

170 "just", 

171 "very", 

172 "really", 

173 "so", 

174 "still", 

175 "always", 

176 "now", 

177 "too", 

178 "to", 

179 "of", 

180 "in", 

181 "on", 

182 "for", 

183 "with", 

184 "ok", 

185 "okay", 

186 "feature", 

187 "code", 

188 "system", 

189 "application", 

190 "app", 

191 "solution", 

192 "implementation", 

193 "functionality", 

194 "program", 

195 "software", 

196 "change", 

197 "changes", 

198 "thing", 

199 "things", 

200 "behaviour", 

201 "behavior", 

202 "result", 

203 "results", 

204 "output", 

205 "overall", 

206 } 

207) 

208_RESULT_VERBS = frozenset( 

209 { 

210 "return", 

211 "returns", 

212 "returned", 

213 "raise", 

214 "raises", 

215 "raised", 

216 "reject", 

217 "rejects", 

218 "rejected", 

219 "accept", 

220 "accepts", 

221 "accepted", 

222 "equal", 

223 "equals", 

224 "contain", 

225 "contains", 

226 "contained", 

227 "list", 

228 "lists", 

229 "listed", 

230 "store", 

231 "stores", 

232 "stored", 

233 "print", 

234 "prints", 

235 "printed", 

236 "exit", 

237 "exits", 

238 "exited", 

239 "respond", 

240 "responds", 

241 "responded", 

242 "create", 

243 "creates", 

244 "created", 

245 "delete", 

246 "deletes", 

247 "deleted", 

248 "match", 

249 "matches", 

250 "matched", 

251 "pass", 

252 "passes", 

253 "passed", 

254 "fail", 

255 "fails", 

256 "failed", 

257 "within", 

258 "before", 

259 "after", 

260 } 

261) 

262_RESULT_PHRASES = ("at most", "at least") 

263_QUALITY_WORDS = { 

264 "fast": "fast", 

265 "faster": "fast", 

266 "quick": "quick", 

267 "quickly": "quick", 

268 "performant": "performant", 

269 "efficient": "efficient", 

270 "efficiently": "efficient", 

271 "scalable": "scalable", 

272 "secure": "secure", 

273 "securely": "secure", 

274 "reliable": "reliable", 

275 "reliably": "reliable", 

276 "responsive": "responsive", 

277} 

278_NUMBER_WORDS = frozenset( 

279 { 

280 "zero", 

281 "one", 

282 "two", 

283 "three", 

284 "four", 

285 "five", 

286 "six", 

287 "seven", 

288 "eight", 

289 "nine", 

290 "ten", 

291 "eleven", 

292 "twelve", 

293 "twenty", 

294 "thirty", 

295 "fifty", 

296 "hundred", 

297 "thousand", 

298 "million", 

299 "half", 

300 "twice", 

301 } 

302) 

303_FILE_EXTENSIONS = ( 

304 "py|pyi|js|mjs|cjs|ts|tsx|jsx|json|yaml|yml|toml|ini|cfg|md|rst|txt|csv|html|css|sh|sql|" 

305 "xml|java|kt|go|rs|rb|php|cs|c|h|cpp|lock|env|log" 

306) 

307 

308_WORD = re.compile(r"[a-z0-9][a-z0-9'_-]*") 

309_DIGIT = re.compile(r"\d") 

310_QUOTED = ( 

311 re.compile(r"`[^`]+`|\"[^\"]+\"|“[^”]+”"), 

312 re.compile(r"‘[^’]+’|(?<![A-Za-z])'[^']+'(?![A-Za-z])"), 

313) 

314_CALL = re.compile(r"[A-Za-z_][\w.]*\(") 

315# Explicit ASCII classes: \w would also match non-ASCII letters, and re.ASCII would change \b. 

316_SNAKE = re.compile(r"\b[A-Za-z][A-Za-z0-9]*_[A-Za-z0-9_]+\b") # NOSONAR(S6353) 

317_PATH = re.compile(r"(?:^|[\s(])\.{0,2}/?[\w.-]+/[\w./-]+") 

318_FILE = re.compile(rf"\b[\w-]+\.(?:{_FILE_EXTENSIONS})\b") 

319_CAMEL = re.compile(r"\b[A-Z][a-z0-9]++(?:[A-Z][a-z0-9]*+)++\b") 

320# What _normalise strips from the end once whitespace runs are single spaces. 

321_TRAILING_CHARS = " .!?;:," 

322_SPACE = re.compile(r"\s+") 

323 

324 

325def _ascii_words(text: str) -> list[str]: 

326 return _WORD.findall(text.lower()) 

327 

328 

329def _lowered(text: str) -> str: 

330 return _SPACE.sub(" ", text.lower()) 

331 

332 

333def _folded(text: str) -> str: 

334 return _SPACE.sub(" ", lang.fold(text)) 

335 

336 

337@dataclass(frozen=True) 

338class _Lexicon: 

339 """The tokenizer, vocabularies and question texts of one intake language.""" 

340 

341 words: Callable[[str], list[str]] 

342 phrase_text: Callable[[str], str] 

343 vague_phrases: tuple[str, ...] 

344 vague_words: frozenset[str] 

345 filler_words: frozenset[str] 

346 result_verbs: frozenset[str] 

347 result_phrases: tuple[str, ...] 

348 quality_words: dict[str, str] 

349 number_words: frozenset[str] 

350 templates: dict[str, str] 

351 

352 

353_LEGACY = _Lexicon( 

354 words=_ascii_words, 

355 phrase_text=_lowered, 

356 vague_phrases=_VAGUE_PHRASES, 

357 vague_words=_VAGUE_WORDS, 

358 filler_words=_FILLER_WORDS, 

359 result_verbs=_RESULT_VERBS, 

360 result_phrases=_RESULT_PHRASES, 

361 quality_words=_QUALITY_WORDS, 

362 number_words=_NUMBER_WORDS, 

363 templates=QUESTION_TEMPLATES, 

364) 

365_ENGLISH = _Lexicon( 

366 words=lang.unicode_words, 

367 phrase_text=_folded, 

368 vague_phrases=_VAGUE_PHRASES, 

369 vague_words=_VAGUE_WORDS, 

370 filler_words=_FILLER_WORDS, 

371 result_verbs=_RESULT_VERBS, 

372 result_phrases=_RESULT_PHRASES, 

373 quality_words=_QUALITY_WORDS, 

374 number_words=_NUMBER_WORDS, 

375 templates=QUESTION_TEMPLATES, 

376) 

377# Spanish tasks keep English code words ("returns", "fast"), so both vocabularies apply. 

378_SPANISH = _Lexicon( 

379 words=lang.unicode_words, 

380 phrase_text=_folded, 

381 vague_phrases=(*_VAGUE_PHRASES, *lang.VAGUE_PHRASES_ES), 

382 vague_words=_VAGUE_WORDS | lang.VAGUE_WORDS_ES, 

383 filler_words=_FILLER_WORDS | lang.FILLER_WORDS_ES, 

384 result_verbs=_RESULT_VERBS | lang.RESULT_VERBS_ES, 

385 result_phrases=(*_RESULT_PHRASES, *lang.RESULT_PHRASES_ES), 

386 quality_words={**_QUALITY_WORDS, **lang.QUALITY_WORDS_ES}, 

387 number_words=_NUMBER_WORDS | lang.NUMBER_WORDS_ES, 

388 templates=lang.QUESTION_TEMPLATES_ES, 

389) 

390 

391 

392def task_text(task: Task) -> str: 

393 """The text language detection reads: title, intent, criteria and their hints.""" 

394 parts = [task.title, task.intent] 

395 for criterion in task.acceptance_criteria: 

396 parts.append(criterion.text) 

397 if criterion.verification_hint: 397 ↛ 398line 397 didn't jump to line 398 because the condition on line 397 was never true

398 parts.append(criterion.verification_hint) 

399 return "\n".join(parts) 

400 

401 

402def resolve_language(task: Task, setting: str | None) -> lang.Language | None: 

403 """The language of a task under ``intake.language``: ``None`` without the key, the 

404 detected one under ``auto``, otherwise the configured one.""" 

405 if setting is None: 

406 return None 

407 if setting == "auto": 

408 return lang.detect_language(task_text(task)) 

409 if setting == "es": 

410 return "es" 

411 if setting == "en": 

412 return "en" 

413 raise ConfigurationError(f"unknown intake language: {setting!r}") 

414 

415 

416def _lexicon(language: str | None) -> _Lexicon: 

417 if language is None: 

418 return _LEGACY 

419 if language == "es": 

420 return _SPANISH 

421 if language == "en": 421 ↛ 423line 421 didn't jump to line 423 because the condition on line 421 was always true

422 return _ENGLISH 

423 raise ConfigurationError(f"unknown intake language: {language!r}") 

424 

425 

426def _has_anchor(text: str, lexicon: _Lexicon = _LEGACY) -> bool: 

427 if ( 

428 _DIGIT.search(text) 

429 or any(pattern.search(text) for pattern in _QUOTED) 

430 or _CALL.search(text) 

431 or _SNAKE.search(text) 

432 or _PATH.search(text) 

433 or _FILE.search(text) 

434 or _CAMEL.search(text) 

435 ): 

436 return True 

437 lowered = lexicon.phrase_text(text) 

438 if any(phrase in lowered for phrase in lexicon.result_phrases): 

439 return True 

440 return any(word in lexicon.result_verbs for word in lexicon.words(text)) 

441 

442 

443def _only_vague(text: str, lexicon: _Lexicon = _LEGACY) -> bool: 

444 """True when the text holds at least one vague term and nothing else but filler.""" 

445 lowered = lexicon.phrase_text(text) 

446 found_phrase = False 

447 for phrase in lexicon.vague_phrases: 

448 if phrase in lowered: 

449 found_phrase = True 

450 lowered = lowered.replace(phrase, " ") 

451 words = lexicon.words(lowered) 

452 vague = [word for word in words if word in lexicon.vague_words] 

453 rest = [ 

454 word 

455 for word in words 

456 if word not in lexicon.vague_words and word not in lexicon.filler_words 

457 ] 

458 return (found_phrase or bool(vague)) and not rest 

459 

460 

461def _has_number(text: str, lexicon: _Lexicon = _LEGACY) -> bool: 

462 return bool(_DIGIT.search(text)) or any( 

463 word in lexicon.number_words for word in lexicon.words(text) 

464 ) 

465 

466 

467def _statement(criterion: AcceptanceCriterion) -> str: 

468 """What a criterion says can be observed: its text and, if any, its verification hint.""" 

469 if criterion.verification_hint and criterion.verification_hint.strip(): 

470 return f"{criterion.text}\n{criterion.verification_hint}" 

471 return criterion.text 

472 

473 

474def _normalise(text: str) -> str: 

475 return _SPACE.sub(" ", text.casefold()).strip().rstrip(_TRAILING_CHARS) 

476 

477 

478def _excerpt(text: str) -> str: 

479 flat = _SPACE.sub(" ", text).strip() 

480 return flat if len(flat) <= _EXCERPT else flat[: _EXCERPT - 3].rstrip() + "..." 

481 

482 

483def no_observable_result(criterion: AcceptanceCriterion, *, language: str | None = None) -> bool: 

484 """Rule C1 (``language``: a resolved intake language, ``None`` for the original rule).""" 

485 lexicon = _lexicon(language) 

486 statement = _statement(criterion) 

487 if _has_anchor(statement, lexicon): 

488 return False 

489 return len(lexicon.words(statement)) < MIN_CRITERION_WORDS or _only_vague(statement, lexicon) 

490 

491 

492def unmeasured_quality( 

493 criterion: AcceptanceCriterion, *, language: str | None = None 

494) -> str | None: 

495 """Rule C2: the first quality word of a criterion without a number, or ``None``.""" 

496 lexicon = _lexicon(language) 

497 statement = _statement(criterion) 

498 if _has_number(statement, lexicon): 

499 return None 

500 for word in lexicon.words(statement): 

501 if word in lexicon.quality_words: 

502 return lexicon.quality_words[word] 

503 return None 

504 

505 

506def scope_without_breakdown(task: Task, *, language: str | None = None) -> bool: 

507 """Rule T1: a short intent, no requirements and a single criterion with no anchor. 

508 

509 A precise single criterion (one with a number, a quoted value, a code identifier or a 

510 result verb) already bounds a small task, so it is not questioned.""" 

511 if len(task.intent.split()) >= MIN_INTENT_WORDS or task.requirements: 

512 return False 

513 if len(task.acceptance_criteria) != 1: 

514 return False 

515 return not _has_anchor(_statement(task.acceptance_criteria[0]), _lexicon(language)) 

516 

517 

518def no_acceptance_criteria(task: Task) -> bool: 

519 """Rule C0.""" 

520 return not task.acceptance_criteria 

521 

522 

523def _basic_findings( 

524 task: Task, topics: tuple[str, ...], language: str | None 

525) -> list[tuple[ClarificationRule, str, str]]: 

526 """One question per fundamental topic (``intake.ambiguityReview.depth: adaptive``), under 

527 ``C0`` when the task has no criteria (where ``C0`` already asks for the results, so the 

528 acceptance topic is left to it) and under ``T1`` otherwise.""" 

529 rule: ClarificationRule = "C0" if no_acceptance_criteria(task) else "T1" 

530 texts = depth.TOPIC_QUESTIONS[depth.topic_language(language)] 

531 title = _excerpt(task.title) 

532 return [ 

533 (rule, depth.TOPIC_TARGET_PREFIX + topic, texts[topic].format(title=title)) 

534 for topic in topics 

535 if not (rule == "C0" and topic == "acceptance") 

536 ] 

537 

538 

539def assess_intent( 

540 task: Task, *, language: str | None = None, basic_topics: tuple[str, ...] = () 

541) -> tuple[ClarificationQuestion, ...]: 

542 """Return the clarification questions for a task, in a stable order. 

543 

544 A task without acceptance criteria gets the seven ``C0`` questions and nothing else: no 

545 criterion can be examined and ``C0`` already asks what ``T1`` would (the behaviours in 

546 scope and what is out of scope). Otherwise criteria are examined in their order (C2, then 

547 C1 unless C2 already applies, then C3), followed by the task-level rule T1. Question ids 

548 are ``Q-1``, ``Q-2``, ... in that order. 

549 

550 ``language`` is the value of ``intake.language`` (``auto``, ``en``, ``es``) or ``None`` 

551 without the key; it changes vocabularies and question texts, never ids, rules or targets. 

552 

553 ``basic_topics`` (``intake.ambiguityReview.depth: adaptive``, see :mod:`.depth`) are 

554 fundamental topics asked first, one question each, with category ``basics`` and target 

555 ``task:<topic>``. Empty, the questions are the ones above. 

556 """ 

557 resolved = resolve_language(task, language) 

558 templates = _lexicon(resolved).templates 

559 findings: list[tuple[ClarificationRule, str, str]] = [] 

560 basics = _basic_findings(task, basic_topics, resolved) if basic_topics else [] 

561 if no_acceptance_criteria(task): 

562 title = _excerpt(task.title) 

563 findings = [ 

564 ("C0", target, templates[key].format(title=title)) 

565 for key, target in zip(_C0_TEMPLATE_KEYS, C0_TARGETS, strict=True) 

566 ] 

567 seen: dict[str, str] = {} 

568 for criterion in task.acceptance_criteria: 

569 values = {"target": criterion.criterion_id, "text": _excerpt(criterion.text)} 

570 term = unmeasured_quality(criterion, language=resolved) 

571 if term is not None: 

572 findings.append( 

573 ("C2", criterion.criterion_id, templates["C2"].format(**values, term=term)) 

574 ) 

575 elif no_observable_result(criterion, language=resolved): 

576 findings.append(("C1", criterion.criterion_id, templates["C1"].format(**values))) 

577 key = _normalise(criterion.text) + "\n" + _normalise(criterion.verification_hint or "") 

578 if key in seen: 

579 findings.append( 

580 ( 

581 "C3", 

582 criterion.criterion_id, 

583 templates["C3"].format(**values, other=seen[key]), 

584 ) 

585 ) 

586 else: 

587 seen[key] = criterion.criterion_id 

588 if scope_without_breakdown(task, language=resolved): 

589 findings.append(("T1", TASK_TARGET, templates["T1"].format(text=_excerpt(task.intent)))) 

590 asked = tuple( 

591 ClarificationQuestion( 

592 question_id=f"Q-{index}", 

593 rule_id=rule, 

594 target=target, 

595 text=text, 

596 category=depth.BASICS_CATEGORY, 

597 ) 

598 for index, (rule, target, text) in enumerate(basics, start=1) 

599 ) 

600 return asked + tuple( 

601 ClarificationQuestion(question_id=f"Q-{index}", rule_id=rule, target=target, text=text) 

602 for index, (rule, target, text) in enumerate(findings, start=len(asked) + 1) 

603 ) 

604 

605 

606def task_digest(task: Task) -> str: 

607 """Digest of a task revision, as stored.""" 

608 return sha256_json(task.model_dump(mode="json", by_alias=True)) 

609 

610 

611@dataclass(frozen=True) 

612class ClarificationInput: 

613 """The content of an answers file: answers by question id and optional task changes.""" 

614 

615 answers: dict[str, str] 

616 replace_criteria: tuple[AcceptanceCriterion, ...] = () 

617 add_criteria: tuple[AcceptanceCriterion, ...] = () 

618 add_requirements: tuple[Requirement, ...] = () 

619 contract: dict[str, Any] | None = None 

620 """Answers to the operational-contract section of the request (since #55), by item.""" 

621 confirm_contract: bool = False 

622 """The person confirms the contract summary the request showed (since #55).""" 

623 

624 

625@dataclass(frozen=True) 

626class TaskRevision: 

627 task: Task 

628 replaced_criteria: tuple[str, ...] 

629 added_criteria: tuple[str, ...] 

630 added_requirements: tuple[str, ...] 

631 

632 

633@dataclass 

634class _Draft: 

635 """The revision being built: criteria, requirements and constraints, with what changed.""" 

636 

637 criteria: list[AcceptanceCriterion] 

638 positions: dict[str, int] 

639 requirements: list[Requirement] 

640 constraints: list[str] 

641 replaced: list[str] = field(default_factory=list) 

642 added_criteria: list[str] = field(default_factory=list) 

643 added_requirements: list[str] = field(default_factory=list) 

644 topics: list[str] = field(default_factory=list) 

645 """Fundamental topics answered in this revision (``depth: adaptive``).""" 

646 

647 def add_criterion(self, criterion: AcceptanceCriterion) -> None: 

648 self.criteria.append(criterion) 

649 self.added_criteria.append(criterion.criterion_id) 

650 

651 def add_requirement(self, requirement: Requirement) -> None: 

652 self.requirements.append(requirement) 

653 self.added_requirements.append(requirement.requirement_id) 

654 

655 

656def _check_answers( 

657 by_id: dict[str, ClarificationQuestion], clarification: ClarificationInput 

658) -> None: 

659 unknown = sorted(set(clarification.answers) - set(by_id)) 

660 if unknown: 

661 raise ConfigurationError(f"unknown question id(s): {', '.join(unknown)}") 

662 if not clarification.answers and not clarification.contract: 

663 raise ConfigurationError("the answers file must answer at least one question") 

664 blank = sorted(qid for qid, text in clarification.answers.items() if not text.strip()) 

665 if blank: 

666 raise ConfigurationError(f"empty answer(s): {', '.join(blank)}") 

667 

668 

669def _replace_criteria(draft: _Draft, clarification: ClarificationInput) -> None: 

670 for replacement in clarification.replace_criteria: 

671 index = draft.positions.get(replacement.criterion_id) 

672 if index is None: 

673 raise ConfigurationError( 

674 f"cannot replace unknown criterion: {replacement.criterion_id}" 

675 ) 

676 if replacement.criterion_id in draft.replaced: 676 ↛ 677line 676 didn't jump to line 677 because the condition on line 676 was never true

677 raise ConfigurationError(f"criterion replaced twice: {replacement.criterion_id}") 

678 draft.criteria[index] = replacement 

679 draft.replaced.append(replacement.criterion_id) 

680 

681 

682def _add_criteria(draft: _Draft, clarification: ClarificationInput) -> None: 

683 for criterion in clarification.add_criteria: 

684 known = criterion.criterion_id in draft.positions 

685 if known or criterion.criterion_id in draft.added_criteria: 

686 raise ConfigurationError(f"criterion id already exists: {criterion.criterion_id}") 

687 draft.add_criterion(criterion) 

688 

689 

690def _add_requirements(draft: _Draft, clarification: ClarificationInput) -> None: 

691 existing_requirements = {item.requirement_id for item in draft.requirements} 

692 for requirement in clarification.add_requirements: 

693 if requirement.requirement_id in existing_requirements: 693 ↛ 694line 693 didn't jump to line 694 because the condition on line 693 was never true

694 raise ConfigurationError(f"requirement id already exists: {requirement.requirement_id}") 

695 draft.requirements.append(requirement) 

696 existing_requirements.add(requirement.requirement_id) 

697 draft.added_requirements.append(requirement.requirement_id) 

698 

699 

700def _explicit_changes(task: Task, clarification: ClarificationInput) -> _Draft: 

701 """The task with the replaced criteria, added criteria and added requirements applied.""" 

702 criteria = list(task.acceptance_criteria) 

703 draft = _Draft( 

704 criteria=criteria, 

705 positions={criterion.criterion_id: index for index, criterion in enumerate(criteria)}, 

706 requirements=list(task.requirements), 

707 constraints=list(task.constraints), 

708 ) 

709 _replace_criteria(draft, clarification) 

710 _add_criteria(draft, clarification) 

711 _add_requirements(draft, clarification) 

712 return draft 

713 

714 

715def _apply_c0_answer( 

716 draft: _Draft, question: ClarificationQuestion, answer: str, clarification: ClarificationInput 

717) -> None: 

718 """A ``C0`` answer lands by its target (see :func:`revise_task`).""" 

719 if question.target == "task:results": 

720 if not clarification.add_criteria: 

721 for line in _answer_lines(answer): 

722 draft.add_criterion(AcceptanceCriterion(criterion_id=new_id("ac"), text=line)) 

723 elif question.target == "task:out-of-scope": 

724 draft.constraints.extend(OUT_OF_SCOPE_PREFIX + line for line in _answer_lines(answer)) 

725 elif question.target in C0_TARGETS and not clarification.add_requirements: 

726 texts = _answer_lines(answer) if question.target == "task:scope" else [answer] 

727 for text in texts: 

728 draft.add_requirement( 

729 Requirement(requirement_id=new_id("req"), text=text, source="clarification") 

730 ) 

731 

732 

733def _extend_hint(draft: _Draft, question: ClarificationQuestion, answer: str) -> None: 

734 """An answer about a criterion that was not replaced becomes (or extends) its hint.""" 

735 if question.target in draft.replaced: 

736 return 

737 index = draft.positions.get(question.target) 

738 if index is None: 738 ↛ 739line 738 didn't jump to line 739 because the condition on line 738 was never true

739 return 

740 current = draft.criteria[index] 

741 hint = ( 

742 f"{current.verification_hint.strip()}\n{answer}" 

743 if current.verification_hint and current.verification_hint.strip() 

744 else answer 

745 ) 

746 draft.criteria[index] = current.model_copy(update={"verification_hint": hint}) 

747 

748 

749def _apply_answer( 

750 draft: _Draft, question: ClarificationQuestion, answer: str, clarification: ClarificationInput 

751) -> None: 

752 """Land one answer in the task where it belongs (see :func:`revise_task`).""" 

753 topic = depth.topic_of(question.target) 

754 if question.category == depth.BASICS_CATEGORY and topic is not None: 

755 # A fundamental topic (depth: adaptive) becomes a requirement under its label. 

756 label = depth.TOPIC_LABELS[_question_language(question, topic)][topic] 

757 draft.add_requirement( 

758 Requirement( 

759 requirement_id=new_id("req"), 

760 text=f"{label}: {' '.join(answer.split())}", 

761 source="clarification", 

762 ) 

763 ) 

764 draft.topics.append(topic) 

765 return 

766 if question.rule_id == "C0": 

767 _apply_c0_answer(draft, question, answer, clarification) 

768 return 

769 if question.rule_id == "P1": 

770 # A project setup answer (#56) is a decision about the project; the task keeps it 

771 # as a constraint so the agent sees it. 

772 part = question.target.removeprefix("project:") 

773 draft.constraints.append(f"Project setup ({part}): {' '.join(answer.split())}") 

774 return 

775 if question.rule_id == "A1" and question.category == "out-of-scope": 

776 # An agent's out-of-scope question is answered with what the task leaves out. 

777 draft.constraints.extend(OUT_OF_SCOPE_PREFIX + line for line in _answer_lines(answer)) 

778 return 

779 if question.target == TASK_TARGET: 

780 if clarification.add_requirements or clarification.add_criteria: 

781 return 

782 draft.add_requirement( 

783 Requirement(requirement_id=new_id("req"), text=answer, source="clarification") 

784 ) 

785 return 

786 _extend_hint(draft, question, answer) 

787 

788 

789def _question_language(question: ClarificationQuestion, topic: str) -> str: 

790 """The language a topic question was asked in: Spanish when its text is the Spanish 

791 template's, otherwise English.""" 

792 spanish = depth.TOPIC_QUESTIONS["es"][topic] 

793 return "es" if question.text.startswith(spanish.split("'", 1)[0]) else "en" 

794 

795 

796def _revised_metadata(task: Task, draft: _Draft) -> dict[str, Any]: 

797 """The metadata of a revision that answered fundamental topics: the topics it covers and, 

798 on the first such revision, the measure of the task as the person wrote it. Without topic 

799 answers the metadata stays as it was.""" 

800 metadata = dict(task.metadata) 

801 if not draft.topics: 

802 return metadata 

803 covered = list(depth.covered_topics(task)) 

804 metadata[depth.TOPICS_KEY] = covered + [t for t in draft.topics if t not in covered] 

805 if depth.frozen_level(task) is None: 805 ↛ 808line 805 didn't jump to line 808 because the condition on line 805 was always true

806 measured = depth.poverty(task) 

807 metadata[depth.DEPTH_KEY] = {"level": measured.level, "score": measured.score} 

808 return metadata 

809 

810 

811def _revised_contract(task: Task, clarification: ClarificationInput) -> dict[str, Any]: 

812 if not clarification.contract: 

813 return {} 

814 # The operational-contract section (since #55): answers update the task's contract. 

815 return { 

816 **(task.contract.model_dump(mode="json", by_alias=True) if task.contract else {}), 

817 **{key: _contract_value(key, value) for key, value in clarification.contract.items()}, 

818 } 

819 

820 

821def revise_task( 

822 task: Task, questions: tuple[ClarificationQuestion, ...], clarification: ClarificationInput 

823) -> TaskRevision: 

824 """Apply a person's answers to a task and return the new revision. 

825 

826 Explicit changes are applied first: replaced criteria (by id), added criteria and added 

827 requirements. An answer then lands in the task where it belongs, so that the revised task 

828 carries it and the next assessment sees it: 

829 

830 * an answer about a criterion that was not replaced becomes (or extends) its 

831 verification hint; 

832 * an answer about the task, when the file adds no requirement or criterion, becomes a 

833 requirement with source ``clarification``; 

834 * an answer to a ``C0`` question lands by its target: ``task:results`` becomes acceptance 

835 criteria, one per non-empty line, unless the file adds criteria; ``task:scope`` becomes 

836 one requirement per non-empty line and ``task:interface``, ``task:limits``, 

837 ``task:errors`` and ``task:non-functional`` one requirement each, unless the file adds 

838 requirements; ``task:out-of-scope`` becomes one constraint per non-empty line, prefixed 

839 with ``Out of scope:``. A leading list marker (``-``, ``*``, ``+``, ``1.``) is removed. 

840 

841 A revision that still has no criteria stays marked ``criteria_pending``, so INTENT asks 

842 the ``C0`` questions again; one that has criteria is no longer marked. 

843 """ 

844 by_id = {question.question_id: question for question in questions} 

845 _check_answers(by_id, clarification) 

846 draft = _explicit_changes(task, clarification) 

847 for question_id in sorted(clarification.answers, key=_question_order): 

848 answer = clarification.answers[question_id].strip() 

849 _apply_answer(draft, by_id[question_id], answer, clarification) 

850 

851 contract = _revised_contract(task, clarification) 

852 try: 

853 revised = Task.model_validate( 

854 { 

855 **task.model_dump(by_alias=True), 

856 "constraints": draft.constraints, 

857 "requirements": [item.model_dump(by_alias=True) for item in draft.requirements], 

858 "criteriaPending": not draft.criteria, 

859 "acceptanceCriteria": [item.model_dump(by_alias=True) for item in draft.criteria], 

860 "metadata": _revised_metadata(task, draft), 

861 **({"contract": contract} if contract else {}), 

862 } 

863 ) 

864 except Exception as error: 

865 raise ConfigurationError(f"invalid revised task: {error}") from error 

866 return TaskRevision( 

867 task=revised, 

868 replaced_criteria=tuple(draft.replaced), 

869 added_criteria=tuple(draft.added_criteria), 

870 added_requirements=tuple(draft.added_requirements), 

871 ) 

872 

873 

874_LIST_MARKER = re.compile(r"^(?:[-*+\u2022]|\d+[.)])(?:\s+|$)") 

875 

876_CONTRACT_LISTS = frozenset({"examples", "scope", "scopePaths", "outOfScope", "definitionOfDone"}) 

877_CONTRACT_FLAGS = frozenset({"push", "createPullRequest", "comment"}) 

878_CONTRACT_KEYS = ( 

879 _CONTRACT_LISTS 

880 | _CONTRACT_FLAGS 

881 | { 

882 "objective", 

883 "verificationLevel", 

884 "branch", 

885 "coverageThreshold", 

886 } 

887) 

888 

889 

890def _contract_value(key: str, value: Any) -> Any: 

891 """An answer to a contract item in the form the task's contract stores it: a list from a 

892 text answer, one item per line; a flag from yes or no.""" 

893 if key not in _CONTRACT_KEYS: 

894 raise ConfigurationError( 

895 f"unknown contract item {key!r}; known: {', '.join(sorted(_CONTRACT_KEYS))}" 

896 ) 

897 if key in _CONTRACT_LISTS and isinstance(value, str): 

898 return _answer_lines(value) 

899 if key in _CONTRACT_FLAGS and isinstance(value, str): 

900 lowered = value.strip().lower() 

901 if lowered in {"yes", "y", "true"}: 

902 return True 

903 if lowered in {"no", "n", "false"}: 903 ↛ 905line 903 didn't jump to line 905 because the condition on line 903 was always true

904 return False 

905 raise ConfigurationError(f"contract item {key} is yes or no, got {value!r}") 

906 return value 

907 

908 

909def _answer_lines(answer: str) -> list[str]: 

910 """The non-empty lines of an answer, without a leading list marker.""" 

911 lines = (_LIST_MARKER.sub("", line.strip()).strip() for line in answer.splitlines()) 

912 return [line for line in lines if line] 

913 

914 

915def _question_order(question_id: str) -> int: 

916 return int(question_id.removeprefix("Q-"))