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
« 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.
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.
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.
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.
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, ...).
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"""
29from __future__ import annotations
31import re
32from collections.abc import Callable
33from dataclasses import dataclass, field
34from typing import Any
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
47from . import depth
48from . import language as lang
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."""
95TASK_TARGET = "task"
96"""Target of a question about the task as a whole rather than one criterion."""
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``).
109Each names the part of the task its answer lands in when the task is revised."""
111OUT_OF_SCOPE_PREFIX = "Out of scope: "
112"""Prefix of the constraints made from the answer about what is out of scope."""
114_C0_TEMPLATE_KEYS = tuple(f"C0{letter}" for letter in "abcdefg")
116MIN_CRITERION_WORDS = 4
117MIN_INTENT_WORDS = 25
118_EXCERPT = 120
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)
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+")
325def _ascii_words(text: str) -> list[str]:
326 return _WORD.findall(text.lower())
329def _lowered(text: str) -> str:
330 return _SPACE.sub(" ", text.lower())
333def _folded(text: str) -> str:
334 return _SPACE.sub(" ", lang.fold(text))
337@dataclass(frozen=True)
338class _Lexicon:
339 """The tokenizer, vocabularies and question texts of one intake language."""
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]
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)
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)
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}")
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}")
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))
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
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 )
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
474def _normalise(text: str) -> str:
475 return _SPACE.sub(" ", text.casefold()).strip().rstrip(_TRAILING_CHARS)
478def _excerpt(text: str) -> str:
479 flat = _SPACE.sub(" ", text).strip()
480 return flat if len(flat) <= _EXCERPT else flat[: _EXCERPT - 3].rstrip() + "..."
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)
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
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.
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))
518def no_acceptance_criteria(task: Task) -> bool:
519 """Rule C0."""
520 return not task.acceptance_criteria
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 ]
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.
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.
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.
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 )
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))
611@dataclass(frozen=True)
612class ClarificationInput:
613 """The content of an answers file: answers by question id and optional task changes."""
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)."""
625@dataclass(frozen=True)
626class TaskRevision:
627 task: Task
628 replaced_criteria: tuple[str, ...]
629 added_criteria: tuple[str, ...]
630 added_requirements: tuple[str, ...]
633@dataclass
634class _Draft:
635 """The revision being built: criteria, requirements and constraints, with what changed."""
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``)."""
647 def add_criterion(self, criterion: AcceptanceCriterion) -> None:
648 self.criteria.append(criterion)
649 self.added_criteria.append(criterion.criterion_id)
651 def add_requirement(self, requirement: Requirement) -> None:
652 self.requirements.append(requirement)
653 self.added_requirements.append(requirement.requirement_id)
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)}")
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)
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)
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)
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
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 )
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})
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)
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"
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
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 }
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.
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:
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.
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)
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 )
874_LIST_MARKER = re.compile(r"^(?:[-*+\u2022]|\d+[.)])(?:\s+|$)")
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)
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
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]
915def _question_order(question_id: str) -> int:
916 return int(question_id.removeprefix("Q-"))