okstra 0.235.0 → 0.237.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/dist/lib/host-registry-client.d.mts +9 -2
  2. package/dist/lib/host-registry-client.mjs +29 -3
  3. package/dist/lib/host-registry-client.mjs.map +1 -1
  4. package/dist/lib/runtime-payload.mjs +1 -0
  5. package/dist/lib/runtime-payload.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +1 -0
  7. package/docs/architecture.md +2 -2
  8. package/docs/cli.md +6 -0
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/bin/lib/okstra/usage.sh +8 -8
  12. package/runtime/bin/okstra-qwen-exec.sh +5 -0
  13. package/runtime/prompts/lead/convergence.md +4 -1
  14. package/runtime/prompts/lead/okstra-lead-contract.md +4 -4
  15. package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
  16. package/runtime/prompts/profiles/_common-contract.md +10 -1
  17. package/runtime/prompts/wizard/prompts.ko.json +16 -4
  18. package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
  19. package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
  20. package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
  21. package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
  22. package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
  23. package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
  24. package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
  25. package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
  26. package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
  27. package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
  28. package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
  29. package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
  30. package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
  31. package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
  32. package/runtime/python/okstra_ctl/convergence.py +95 -5
  33. package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
  34. package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
  35. package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
  36. package/runtime/python/okstra_ctl/coverage_census.py +75 -12
  37. package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
  38. package/runtime/python/okstra_ctl/lead_progress.py +1 -1
  39. package/runtime/python/okstra_ctl/manager_cli.py +42 -5
  40. package/runtime/python/okstra_ctl/manager_launch.py +60 -1
  41. package/runtime/python/okstra_ctl/manager_store.py +45 -0
  42. package/runtime/python/okstra_ctl/model_discovery.py +1 -1
  43. package/runtime/python/okstra_ctl/models.py +2 -2
  44. package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
  45. package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  47. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
  48. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
  50. package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
  51. package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
  52. package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
  53. package/runtime/python/okstra_ctl/render_final_report.py +1 -1
  54. package/runtime/python/okstra_ctl/run.py +1 -1
  55. package/runtime/python/okstra_ctl/run_context.py +18 -3
  56. package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
  57. package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
  58. package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
  59. package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
  60. package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
  61. package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
  62. package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
  63. package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
  64. package/runtime/python/okstra_ctl/wizard/state.py +71 -21
  65. package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
  66. package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
  67. package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
  68. package/runtime/python/okstra_ctl/worker_audit_ledger.py +50 -8
  69. package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
  70. package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
  71. package/runtime/python/okstra_token_usage/claude.py +5 -1
  72. package/runtime/python/okstra_token_usage/collect.py +3 -3
  73. package/runtime/python/okstra_token_usage/pricing.py +1 -0
  74. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  75. package/runtime/skills/okstra-discussion/SKILL.md +1 -1
  76. package/runtime/skills/okstra-manager/SKILL.md +8 -2
  77. package/runtime/skills/okstra-run/SKILL.md +2 -2
  78. package/runtime/skills/okstra-setup/SKILL.md +34 -5
  79. package/runtime/skills/okstra-setup/references/project-config.md +19 -0
  80. package/runtime/templates/worker-prompt-preamble.md +12 -2
@@ -0,0 +1,88 @@
1
+ """Qwen Code workers using a regional Model Studio API endpoint."""
2
+ import os
3
+ import re
4
+ from collections.abc import Mapping
5
+ from pathlib import Path
6
+ from typing import Any
7
+ from urllib.parse import urlsplit
8
+
9
+ from okstra_ctl.domain.provider import ModelSpec, ProviderSpec
10
+ from okstra_ctl.domain.role import ROLE_DEFINITIONS
11
+ from okstra_ctl.domain.worker_exec import ExecCommand, PolicySupport, WorkerExecRequest
12
+ from okstra_ctl.domain.worker_presentation import JsonEvents
13
+ from okstra_ctl.domain.worker_stream import content_block_events
14
+
15
+
16
+ def observe_usage(event: Mapping[str, Any]) -> Mapping[str, Any] | None:
17
+ usage = event.get("usage") if event.get("type") == "result" else None
18
+ return usage if isinstance(usage, Mapping) and usage else None
19
+
20
+
21
+ class QwenExecution:
22
+ def build_command(self, request: WorkerExecRequest) -> ExecCommand:
23
+ api_key = os.environ.get("DASHSCOPE_API_KEY", "").strip()
24
+ endpoint = os.environ.get("OKSTRA_QWEN_BASE_URL", "").strip()
25
+ if not api_key:
26
+ raise OSError("DASHSCOPE_API_KEY is required for Qwen workers")
27
+ if not endpoint:
28
+ raise OSError("OKSTRA_QWEN_BASE_URL is required for Qwen workers")
29
+ try:
30
+ parsed = urlsplit(endpoint)
31
+ port = parsed.port
32
+ except ValueError:
33
+ raise OSError("OKSTRA_QWEN_BASE_URL is not a valid Model Studio URL") from None
34
+ host = parsed.hostname or ""
35
+ if parsed.username is not None or parsed.password is not None:
36
+ raise OSError("OKSTRA_QWEN_BASE_URL must not embed credentials")
37
+ regional = re.fullmatch(r"[a-z0-9-]+\.[a-z0-9-]+\.maas\.aliyuncs\.com", host)
38
+ legacy = host in {"dashscope.aliyuncs.com", "dashscope-intl.aliyuncs.com", "cn-hongkong.dashscope.aliyuncs.com"}
39
+ if (parsed.scheme != "https" or not (regional or legacy)
40
+ or port not in (None, 443) or parsed.query or parsed.fragment
41
+ or parsed.path.rstrip("/") != "/compatible-mode/v1"):
42
+ raise OSError("OKSTRA_QWEN_BASE_URL must be an HTTPS Model Studio /compatible-mode/v1 URL without credentials, query or fragment")
43
+ argv = [
44
+ "qwen", "--auth-type", "openai", "--openai-base-url", endpoint,
45
+ "--model", request.model, "--output-format", "stream-json",
46
+ ]
47
+ if request.policy.auto_approve:
48
+ argv += ["--approval-mode", "yolo"]
49
+ if request.session_id:
50
+ argv += ["--session-id", request.session_id]
51
+ for directory in request.policy.write_scope:
52
+ argv += ["--include-directories", str(directory)]
53
+ return ExecCommand(
54
+ argv=tuple(argv), stdin_text=request.prompt_text,
55
+ cwd=request.worktree_path or request.project_root,
56
+ environment={
57
+ "OPENAI_API_KEY": api_key, "OPENAI_MODEL": request.model,
58
+ "OKSTRA_QWEN_API_KEY": api_key, "OKSTRA_QWEN_ENDPOINT": endpoint,
59
+ "QWEN_CODE_SYSTEM_SETTINGS_PATH": str(Path(__file__).with_name("settings.json")),
60
+ },
61
+ presentation=JsonEvents(
62
+ normalise=content_block_events,
63
+ # Qwen Code copies config.getModel() into message.model.
64
+ observe=lambda _event: None,
65
+ observe_usage=observe_usage,
66
+ ),
67
+ )
68
+
69
+ def policy_support(self) -> PolicySupport:
70
+ return PolicySupport(
71
+ can_auto_approve=True, can_bound_write_scope=False,
72
+ note="Qwen Code approval mode does not enforce filesystem write boundaries",
73
+ )
74
+
75
+
76
+ def create_provider() -> ProviderSpec:
77
+ roles = frozenset(role.id for role in ROLE_DEFINITIONS if role.id != "leader")
78
+ return ProviderSpec(
79
+ provider="qwen", display_label="Qwen Code",
80
+ models={"qwen4-max": ModelSpec("qwen4-max", "Qwen4 Max", "qwen4-max")},
81
+ default_models={role: "qwen4-max" for role in roles},
82
+ wrapper="okstra-qwen-exec.sh", supported_roles=roles,
83
+ execution_capabilities=frozenset({
84
+ "worker-artifact-io", "source-readonly",
85
+ "extended-artifact-authoring", "project-mutation",
86
+ }),
87
+ exec_strategy=QwenExecution(),
88
+ )
@@ -0,0 +1 @@
1
+ {"schemaVersion": 1, "id": "qwen", "factory": "adapter.py:create_provider"}
@@ -0,0 +1,12 @@
1
+ {
2
+ "modelProviders": {
3
+ "openai": [
4
+ {
5
+ "id": "qwen4-max",
6
+ "envKey": "OKSTRA_QWEN_API_KEY",
7
+ "baseUrl": "${OKSTRA_QWEN_ENDPOINT}"
8
+ }
9
+ ]
10
+ },
11
+ "$version": 4
12
+ }
@@ -25,6 +25,8 @@ ZAI_MODELS = {
25
25
  for name, label, pricing in (
26
26
  ("glm-5.3", "GLM-5.3", (1.40, 0.26, 4.40)),
27
27
  ("glm-5.3-flash", "GLM-5.3 Flash", (0.15, 0.03, 0.50)),
28
+ ("glm-5.3-flashx", "GLM-5.3 FlashX", (0.37, 0.075, 1.25)),
29
+ ("glm-5.3-flashx-legal", "GLM-5.3 FlashX Legal", (0.37, 0.075, 1.25)),
28
30
  )
29
31
  }
30
32
 
@@ -88,10 +90,14 @@ class ZaiExecution:
88
90
  command = ClaudeExecution().build_command(
89
91
  replace(request, reasoning_effort="")
90
92
  )
93
+ argv = list(command.argv)
94
+ index = argv.index("--setting-sources")
95
+ # No setting source at all, so a settings file's env cannot override the
96
+ # child environment below.
97
+ argv[index + 1] = ""
91
98
  return replace(
92
99
  command,
93
- # 설정 파일의 env 가 자식 환경을 다시 덮어쓰지 않게 한다.
94
- argv=(*command.argv, "--setting-sources", ""),
100
+ argv=tuple(argv),
95
101
  environment={
96
102
  "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
97
103
  "ANTHROPIC_AUTH_TOKEN": api_key,
@@ -11,6 +11,7 @@ from dataclasses import dataclass
11
11
  from pathlib import Path
12
12
  from typing import Any, Mapping, Sequence
13
13
 
14
+ from .clarification_items.dispositions import USER_INPUT_BLOCKS
14
15
  from .clarification_items.sidecars import (
15
16
  sidecar_answers,
16
17
  attached_response_sections,
@@ -57,6 +58,10 @@ SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
57
58
  CLASSIFICATIONS = frozenset(
58
59
  {"user-decision", "noncritical-dissent", "correctness-critical"}
59
60
  )
61
+ # A phase without an approval gate records its decisions as next-phase blockers
62
+ # (`_common-contract.md` reporter-confirmation precondition); both are the values
63
+ # the gates read as waiting on user input.
64
+ DECISION_BLOCKS = tuple(sorted(USER_INPUT_BLOCKS))
60
65
  _FORBIDDEN_BY_CLASSIFICATION = {
61
66
  "correctness-critical": frozenset({"select"}),
62
67
  "noncritical-dissent": frozenset({"select"}),
@@ -214,7 +219,12 @@ def _decision_row(
214
219
  expected_form: str, classification: str, origin: str,
215
220
  user_confirmation: str, unblock_condition: str,
216
221
  recommended_disposition: str, options: Sequence[DecisionOption],
222
+ blocks: str = "approval",
217
223
  ) -> dict[str, Any]:
224
+ if blocks not in DECISION_BLOCKS:
225
+ raise ApprovalDecisionError(
226
+ f"invalid blocks: {blocks!r}. Allowed values: " + ", ".join(DECISION_BLOCKS)
227
+ )
218
228
  if classification not in CLASSIFICATIONS:
219
229
  raise ApprovalDecisionError(f"invalid classification: {classification}")
220
230
  _reject_off_enum(origin, "origin", "ClarificationOrigin")
@@ -232,7 +242,7 @@ def _decision_row(
232
242
  "kind": "decision",
233
243
  "statement": _required(statement, "statement"),
234
244
  "expectedForm": _required(expected_form, "expected_form"),
235
- "blocks": "approval",
245
+ "blocks": blocks,
236
246
  "origin": _required(origin, "origin"),
237
247
  "userConfirmation": _required(user_confirmation, "user_confirmation"),
238
248
  "approval": {
@@ -250,7 +260,7 @@ def open_decision(
250
260
  classification: str, origin: str, user_confirmation: str,
251
261
  unblock_condition: str, recommended_disposition: str,
252
262
  options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
253
- candidate_ref: str = "",
263
+ candidate_ref: str = "", blocks: str = "approval",
254
264
  ) -> None:
255
265
  row = _decision_row(
256
266
  clarification_id=clarification_id, ticket_id=ticket_id,
@@ -258,6 +268,7 @@ def open_decision(
258
268
  classification=classification, origin=origin,
259
269
  user_confirmation=user_confirmation, unblock_condition=unblock_condition,
260
270
  recommended_disposition=recommended_disposition, options=options,
271
+ blocks=blocks,
261
272
  )
262
273
  ledger = _ledger(ledger_path, task_key, task_type, run_seq)
263
274
  active = ledger.get("activeClarifications")
@@ -487,6 +498,15 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
487
498
  "candidate's splitAcceptance may cite only a decision opened for it."
488
499
  ),
489
500
  )
501
+ parser.add_argument(
502
+ "--blocks",
503
+ choices=DECISION_BLOCKS,
504
+ default="approval",
505
+ help=(
506
+ "what the open row withholds: approval (the default) or next-phase, "
507
+ "for a phase without an approval gate"
508
+ ),
509
+ )
490
510
 
491
511
 
492
512
  _CLI_EPILOG = r"""Usage:
@@ -10,6 +10,7 @@ from typing import Any, Literal, TypedDict
10
10
  from ..report_language import resolve_report_language
11
11
  from ..json_boundary import load_owned_object, write_owned_object_atomic
12
12
  from ..paths import find_asset_root
13
+ from ..schema_excerpt import reachable_defs
13
14
  from ..report_language import is_language_tag
14
15
 
15
16
  OPERATION = "explain-flow"
@@ -267,6 +268,16 @@ def schema_definition(name: str) -> dict[str, Any]:
267
268
  return {"$ref": f"#/$defs/{name}", "$defs": schema["$defs"]}
268
269
 
269
270
 
271
+ def prompt_schema(name: str) -> dict[str, Any]:
272
+ """`schema_definition` with only the definitions `name` reaches through
273
+ `$ref`; the stored records (claims, executions, task links) are not part of
274
+ what a model returns."""
275
+ schema = schema_definition(name)
276
+ defs = schema["$defs"]
277
+ kept = reachable_defs(defs, {"$ref": schema["$ref"]})
278
+ return {**schema, "$defs": {key: defs[key] for key in defs if key in kept}}
279
+
280
+
270
281
  def read_artifact(path: Path, name: str) -> dict[str, Any]:
271
282
  return load_owned_object(
272
283
  path, artifact=f"business flow {name}", schema=schema_definition(name)
@@ -3,6 +3,7 @@ from __future__ import annotations
3
3
  import hashlib
4
4
  import json
5
5
  import re
6
+ from collections import Counter
6
7
  from dataclasses import asdict, replace
7
8
  from datetime import datetime, timezone
8
9
  from pathlib import Path
@@ -27,6 +28,7 @@ from .contracts import (
27
28
  SourceSnapshot,
28
29
  artifact_path,
29
30
  now_iso,
31
+ prompt_schema,
30
32
  read_artifact,
31
33
  schema_definition,
32
34
  write_artifact,
@@ -40,11 +42,14 @@ from .source import (
40
42
  validate_evidence,
41
43
  )
42
44
  from .store import (
45
+ conflict_groups,
43
46
  contribute_knowledge,
44
47
  query_knowledge,
45
48
  read_shared_knowledge,
46
49
  record_task_execution,
47
50
  resolve_conflicts,
51
+ split_by_focus,
52
+ task_focus,
48
53
  validate_resolutions,
49
54
  )
50
55
 
@@ -298,7 +303,9 @@ def _validate_fact_evidence(
298
303
  "confirmed business claims require inspected code evidence"
299
304
  )
300
305
  for evidence in fact["evidence"]:
301
- evidence["excerpt"] = validate_evidence(evidence, projects)
306
+ evidence["excerpt"], evidence["line"], evidence["endLine"] = validate_evidence(
307
+ evidence, projects
308
+ )
302
309
  if evidence["projectId"] not in result["inspectedProjects"]:
303
310
  raise BusinessFlowError(
304
311
  "claim evidence references an uninspected candidate"
@@ -379,7 +386,7 @@ def _instructions(
379
386
  request: FlowRequest, execution: FlowExecution, baseline: FlowExecution | None
380
387
  ) -> str:
381
388
  context = _investigation_context(request, execution, baseline)
382
- schema = schema_definition("result")
389
+ schema = prompt_schema("result")
383
390
  return "\n".join(
384
391
  [
385
392
  "# Business Flow Investigation",
@@ -395,12 +402,15 @@ def _instructions(
395
402
  "For post mode, use the supplied project-specific baseline. Never invent missing before-state. Describe the actual delta and distinguish confirmed side effects from risks.",
396
403
  "For contribute mode, extract newly observed business facts from the supplied validated task record and inspect source to confirm them. Empty facts are valid. Do not copy the report narrative as established truth.",
397
404
  "For reconcile mode, reinspect every conflicting source and condition. Return explicit resolutions only with evidence-backed reasoning and original claimIds/acceptedClaimId. Preserve genuinely unresolved policy decisions in questions. Other modes return resolutions=[].",
405
+ "knowledge.conflictGroups lists each active conflict: the claims that disagree on one key at one source version. A resolution's claimIds must be exactly one group's claimIds, never claims of the same key from another group, and acceptedClaimId one of them. Resolve only groups whose freshness is current; a historical group's source has changed since and stays a conflict. Return the accepted claim's key, value and level unchanged as a fact with evidence you reinspected.",
406
+ "Stored knowledge claims cite evidence as projectId:path:line-endLine. knowledge.notShown counts, by business, stored claims that do not mention this task; look one up with `okstra explain-flow knowledge --query <business question>` when it applies.",
398
407
  "Keep fact keys, business identifiers and fact values canonical in English; preserve original business terms in aliases. Do not create conflicts by translating the same fact. Read source evidence before accepting stored knowledge, including other projects' claims.",
399
408
  "execution-verified requires a supplied JSON verificationReceipt with command, startedAt, endedAt, exitCode=0, output and matching projectId-to-digest sourceStates. A final report alone is not an execution receipt.",
409
+ 'Each terms item has exactly two fields: {"term": "<business term>", "meaning": "<what it means here>"}.',
400
410
  f"Write report titles, summaries, terms, steps, relationship data, gaps and questions in {request.report_language}; preserve paths, identifiers and enum values.",
401
411
  "",
402
412
  "## Source Material and Captured Baseline",
403
- json.dumps(context, ensure_ascii=False, indent=2),
413
+ json.dumps(context, ensure_ascii=False, separators=(",", ":")),
404
414
  "",
405
415
  "## Result Schema",
406
416
  json.dumps(schema, ensure_ascii=False, indent=2),
@@ -412,6 +422,7 @@ def _instructions(
412
422
  def _investigation_context(
413
423
  request: FlowRequest, execution: FlowExecution, baseline: FlowExecution | None
414
424
  ) -> dict[str, Any]:
425
+ knowledge = _investigation_knowledge(request)
415
426
  compact = [
416
427
  {
417
428
  "projectId": row["projectId"],
@@ -441,13 +452,65 @@ def _investigation_context(
441
452
  )
442
453
  if baseline
443
454
  else "",
444
- "knowledge": query_knowledge(
445
- request.project_root,
446
- request.question,
447
- request.source_root,
448
- request.project_group,
449
- members_only=request.mode != "reconcile",
450
- ),
455
+ "knowledge": {**knowledge, "claims": [_prompt_claim(row) for row in knowledge["claims"]]},
456
+ }
457
+
458
+
459
+ _PROMPT_CLAIM_FIELDS = ("id", "key", "business", "value", "level", "status", "freshness")
460
+
461
+
462
+ def _prompt_claim(row: dict[str, Any]) -> dict[str, Any]:
463
+ """The investigator re-reads a claim's source before relying on it, so the
464
+ producers, source states and evidence excerpts stay in the store."""
465
+ claim = {field: row[field] for field in _PROMPT_CLAIM_FIELDS}
466
+ claim.update({field: row[field] for field in ("aliases", "relatedKeys") if row.get(field)})
467
+ claim["evidence"] = [
468
+ f"{item['projectId']}:{item['path']}:{item['line']}-{item['endLine']}"
469
+ for item in row["evidence"]
470
+ ]
471
+ return claim
472
+
473
+
474
+ def _investigation_knowledge(request: FlowRequest) -> dict[str, Any]:
475
+ """Stored claims for an investigation.
476
+
477
+ A task's question is its whole brief, whose words select nearly every stored
478
+ claim, so a task investigation keeps the claims that mention the task's
479
+ focus terms and counts the rest by business. A reconcile question names
480
+ its conflict keys and is not narrowed; it also gets the conflict groups,
481
+ because a resolution must cover exactly one and the claims no longer carry
482
+ the source versions that tell the groups apart.
483
+ """
484
+ result = query_knowledge(
485
+ request.project_root,
486
+ request.question,
487
+ request.source_root,
488
+ request.project_group,
489
+ members_only=request.mode != "reconcile",
490
+ )
491
+ claims = result["claims"]
492
+ if request.mode == "reconcile":
493
+ return {
494
+ "claims": claims,
495
+ "conflictGroups": [
496
+ {
497
+ "key": group[0]["key"],
498
+ "freshness": group[0]["freshness"],
499
+ "claimIds": sorted(row["id"] for row in group),
500
+ }
501
+ for group in conflict_groups(claims)
502
+ ],
503
+ "notShown": {},
504
+ "errors": result["errors"],
505
+ }
506
+ focus = task_focus(request.task_key, request.question) if request.task_key else ()
507
+ if not focus:
508
+ return {"claims": claims, "notShown": {}, "errors": result["errors"]}
509
+ focused, others = split_by_focus(claims, focus)
510
+ return {
511
+ "claims": focused,
512
+ "notShown": dict(Counter(row["business"] for row in others).most_common()),
513
+ "errors": result["errors"],
451
514
  }
452
515
 
453
516
 
@@ -456,16 +519,7 @@ def _reinvestigate_conflicts(
456
519
  ) -> None:
457
520
  if request.mode == "reconcile":
458
521
  return
459
- conflict_keys = {
460
- row["key"]
461
- for row in query_knowledge(
462
- request.project_root,
463
- request.question,
464
- request.source_root,
465
- request.project_group,
466
- )["claims"]
467
- if row["status"] == "conflict"
468
- }
522
+ conflict_keys = _conflict_keys(request, execution)
469
523
  if not conflict_keys:
470
524
  return
471
525
  child = explain_flow(
@@ -483,25 +537,29 @@ def _reinvestigate_conflicts(
483
537
  "error": child.get("error", ""),
484
538
  "questions": child.get("result", {}).get("questions", []),
485
539
  }
486
- unresolved = [
487
- row["key"]
488
- for row in query_knowledge(
489
- request.project_root,
490
- request.question,
491
- request.source_root,
492
- request.project_group,
493
- )["claims"]
494
- if row["status"] == "conflict"
495
- ]
540
+ unresolved = _conflict_keys(request, execution)
496
541
  if unresolved:
497
542
  execution["result"]["questions"].append(
498
- "Unresolved shared business conflicts: "
499
- + ", ".join(sorted(set(unresolved)))
543
+ "Unresolved shared business conflicts: " + ", ".join(sorted(unresolved))
500
544
  )
501
545
  execution["status"] = "partial"
502
546
  write_artifact(path, execution, "execution")
503
547
 
504
548
 
549
+ def _conflict_keys(request: FlowRequest, execution: FlowExecution) -> set[str]:
550
+ """Conflicts this explanation answers for: among the claims its investigator
551
+ was shown, and on a key it returned, which is where a conflict it created
552
+ lies even when the claim does not mention the task."""
553
+ returned = {fact["key"] for fact in execution["result"]["facts"]}
554
+ shown = _investigation_knowledge(request)["claims"]
555
+ stored = read_shared_knowledge(request.project_root, request.project_group)["claims"]
556
+ return {
557
+ row["key"]
558
+ for row in [*shown, *(row for row in stored if row["key"] in returned)]
559
+ if row["status"] == "conflict"
560
+ }
561
+
562
+
505
563
  def load_execution(project_root: Path, execution_id: str) -> FlowExecution:
506
564
  if not execution_id or any(
507
565
  char not in "abcdefghijklmnopqrstuvwxyz0123456789-" for char in execution_id
@@ -17,7 +17,7 @@ from .contracts import (
17
17
  from .engine import explain_flow, load_execution
18
18
  from .invocation import FlowExecutor
19
19
  from .source import candidate_projects, capture_projects, changed_projects
20
- from .store import knowledge_packet, read_task_links, record_task_execution
20
+ from .store import knowledge_packet, read_task_links, record_task_execution, task_focus
21
21
 
22
22
 
23
23
  def prepare_task_knowledge(
@@ -58,7 +58,9 @@ def prepare_task_knowledge(
58
58
  _ensure_pre_explanation(project_root, request, executor)
59
59
  except (OSError, ValueError, JsonBoundaryError) as exc:
60
60
  return f"## Shared Business Knowledge\n\nBusiness preparation failed: {exc}\n"
61
- return knowledge_packet(project_root, question, Path(source))
61
+ return knowledge_packet(
62
+ project_root, question, Path(source), task_focus(str(ctx.get("TASK_KEY", "")), question)
63
+ )
62
64
 
63
65
 
64
66
  def _flow_request(
@@ -168,7 +168,12 @@ def capture_projects(candidates: list[ProjectCandidate]) -> list[SourceSnapshot]
168
168
 
169
169
  def validate_evidence(
170
170
  evidence: BusinessEvidence, projects: list[SourceSnapshot]
171
- ) -> str:
171
+ ) -> tuple[str, int, int]:
172
+ """The source lines that hold the excerpt, and their range.
173
+
174
+ The range is the cited one, or the nearest one within two lines that holds
175
+ the excerpt.
176
+ """
172
177
  project = next(
173
178
  (row for row in projects if row["projectId"] == evidence["projectId"]), None
174
179
  )
@@ -190,15 +195,42 @@ def validate_evidence(
190
195
  start, end = evidence["line"], evidence["endLine"]
191
196
  if end < start or end > len(lines):
192
197
  raise BusinessFlowError("evidence line range is invalid")
193
- source = lines[start - 1 : end]
194
- if not _excerpt_matches(evidence["excerpt"], source):
195
- raise BusinessFlowError(
196
- f"evidence excerpt does not match source: {evidence['path']}:{start}"
197
- )
198
- return "\n".join(source)
198
+ if not _excerpt_matches(evidence["excerpt"], lines[start - 1 : end]):
199
+ located = _nearby_range(evidence["excerpt"], lines, start, end)
200
+ if located is None:
201
+ raise BusinessFlowError(
202
+ f"evidence excerpt does not match source: {evidence['path']}:{start}"
203
+ )
204
+ start, end = located
205
+ return "\n".join(lines[start - 1 : end]), start, end
199
206
 
200
207
 
201
208
  _ELISION_MARKERS = {"...", "\u2026"}
209
+ _LINE_DRIFT = 2
210
+
211
+
212
+ def _nearby_range(
213
+ excerpt: str, lines: list[str], start: int, end: int
214
+ ) -> tuple[int, int] | None:
215
+ """The shortest, then closest, range within two lines of the cited one that
216
+ holds the excerpt.
217
+
218
+ Investigators copy the right lines but often count the range a line off. A
219
+ wider range also holds the excerpt, so the shortest one is where it is.
220
+ """
221
+ candidates = sorted(
222
+ (last - first, abs(first - start) + abs(last - end), first, last)
223
+ for first in range(max(1, start - _LINE_DRIFT), start + _LINE_DRIFT + 1)
224
+ for last in range(max(first, end - _LINE_DRIFT), min(len(lines), end + _LINE_DRIFT) + 1)
225
+ )
226
+ return next(
227
+ (
228
+ (first, last)
229
+ for _, _, first, last in candidates
230
+ if _excerpt_matches(excerpt, lines[first - 1 : last])
231
+ ),
232
+ None,
233
+ )
202
234
 
203
235
 
204
236
  def _excerpt_matches(excerpt: str, source: list[str]) -> bool: