okstra 0.231.1 → 0.233.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 (265) hide show
  1. package/README.md +19 -271
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/memory/memory.mjs +9 -55
  10. package/dist/commands/memory/memory.mjs.map +1 -1
  11. package/dist/commands/trace/capacity.d.mts +12 -0
  12. package/dist/commands/trace/capacity.mjs +21 -0
  13. package/dist/commands/trace/capacity.mjs.map +1 -0
  14. package/dist/commands/trace/model.d.mts +89 -0
  15. package/dist/commands/trace/model.mjs +251 -0
  16. package/dist/commands/trace/model.mjs.map +1 -0
  17. package/dist/commands/trace/progression.d.mts +11 -0
  18. package/dist/commands/trace/progression.mjs +194 -0
  19. package/dist/commands/trace/progression.mjs.map +1 -0
  20. package/dist/commands/trace/review.d.mts +7 -0
  21. package/dist/commands/trace/review.mjs +51 -0
  22. package/dist/commands/trace/review.mjs.map +1 -0
  23. package/dist/commands/trace/task-link.d.mts +18 -0
  24. package/dist/commands/trace/task-link.mjs +72 -0
  25. package/dist/commands/trace/task-link.mjs.map +1 -0
  26. package/dist/commands/trace/trace.d.mts +1 -0
  27. package/dist/commands/trace/trace.mjs +293 -0
  28. package/dist/commands/trace/trace.mjs.map +1 -0
  29. package/dist/lib/bounded-file.d.mts +1 -0
  30. package/dist/lib/bounded-file.mjs +36 -0
  31. package/dist/lib/bounded-file.mjs.map +1 -0
  32. package/dist/lib/config-store.d.mts +34 -0
  33. package/dist/lib/config-store.mjs +70 -0
  34. package/dist/lib/config-store.mjs.map +1 -0
  35. package/dist/lib/file-lock.mjs +4 -5
  36. package/dist/lib/file-lock.mjs.map +1 -1
  37. package/dist/lib/input-limit.d.mts +4 -0
  38. package/dist/lib/input-limit.mjs +8 -0
  39. package/dist/lib/input-limit.mjs.map +1 -0
  40. package/dist/lib/memory-auto-register.d.mts +1 -0
  41. package/dist/lib/memory-auto-register.mjs +98 -0
  42. package/dist/lib/memory-auto-register.mjs.map +1 -0
  43. package/dist/lib/memory-entry-contract.d.mts +12 -0
  44. package/dist/lib/memory-entry-contract.mjs +46 -0
  45. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  46. package/dist/lib/python-helper.d.mts +1 -1
  47. package/dist/lib/python-helper.mjs +3 -2
  48. package/dist/lib/python-helper.mjs.map +1 -1
  49. package/dist/lib/record-secrets.d.mts +1 -0
  50. package/dist/lib/record-secrets.mjs +28 -0
  51. package/dist/lib/record-secrets.mjs.map +1 -0
  52. package/dist/lib/report-language-tag.d.mts +1 -0
  53. package/dist/lib/report-language-tag.mjs +4 -0
  54. package/dist/lib/report-language-tag.mjs.map +1 -0
  55. package/dist/lib/report-language.d.mts +1 -0
  56. package/dist/lib/report-language.mjs +50 -0
  57. package/dist/lib/report-language.mjs.map +1 -0
  58. package/dist/lib/skill-catalog.mjs +3 -0
  59. package/dist/lib/skill-catalog.mjs.map +1 -1
  60. package/dist/lib/types.d.mts +2 -1
  61. package/docs/architecture/storage-model.md +163 -5
  62. package/docs/architecture.md +17 -4
  63. package/docs/cli.md +511 -0
  64. package/docs/contributor-change-matrix.md +1 -2
  65. package/docs/project-structure-overview.md +33 -42
  66. package/package.json +1 -1
  67. package/runtime/BUILD.json +2 -2
  68. package/runtime/agents/common.json +8 -8
  69. package/runtime/agents/operations/trace-interface-review.json +6 -0
  70. package/runtime/agents/operations/trace-scope-review.json +6 -0
  71. package/runtime/agents/roles/verifier.json +2 -4
  72. package/runtime/bin/okstra-provider-exec.py +10 -4
  73. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  74. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  75. package/runtime/prompts/coding-preflight/clean-code.md +88 -286
  76. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  77. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  78. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  79. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  80. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  81. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  82. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  83. package/runtime/prompts/coding-preflight/overview.md +25 -38
  84. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  85. package/runtime/prompts/duties/code-reviewer.json +15 -18
  86. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  87. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  88. package/runtime/prompts/host-orchestration/README.md +18 -9
  89. package/runtime/prompts/launch.template.md +3 -2
  90. package/runtime/prompts/lead/context-loader.md +2 -0
  91. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  92. package/runtime/prompts/lead/report-writer.md +6 -6
  93. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  94. package/runtime/prompts/profiles/_common-contract.md +1 -1
  95. package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
  96. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
  97. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  98. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
  99. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  100. package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
  101. package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
  102. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  103. package/runtime/python/okstra_ctl/code_review_census.py +162 -7
  104. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  105. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  106. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  107. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  108. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  109. package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
  110. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  111. package/runtime/python/okstra_ctl/code_review_target.py +212 -13
  112. package/runtime/python/okstra_ctl/consumers.py +12 -9
  113. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  114. package/runtime/python/okstra_ctl/design_review.py +207 -0
  115. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  116. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  117. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  118. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  119. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  120. package/runtime/python/okstra_ctl/doctor.py +8 -25
  121. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  122. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  123. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  124. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  125. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  126. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  127. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  128. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  129. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  130. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  131. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  132. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  133. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
  134. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  135. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  136. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  137. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  138. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  139. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  140. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  141. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  142. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  143. package/runtime/python/okstra_ctl/json_boundary.py +51 -5
  144. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  145. package/runtime/python/okstra_ctl/manager_cli.py +148 -1
  146. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  147. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  148. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  149. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  150. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  151. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  152. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  153. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  154. package/runtime/python/okstra_ctl/manager_sync.py +45 -25
  155. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  156. package/runtime/python/okstra_ctl/material.py +2 -0
  157. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  158. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  159. package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
  160. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  161. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  162. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  163. package/runtime/python/okstra_ctl/paths.py +6 -1
  164. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  165. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  166. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  167. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  168. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
  169. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
  170. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  171. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  172. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  173. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  174. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  175. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  176. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
  177. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  178. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  179. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
  180. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  181. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  182. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  183. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  184. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  185. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  186. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  187. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  188. package/runtime/python/okstra_ctl/render.py +28 -2
  189. package/runtime/python/okstra_ctl/report_assembly.py +53 -11
  190. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  191. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  192. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  193. package/runtime/python/okstra_ctl/report_language.py +4 -1
  194. package/runtime/python/okstra_ctl/report_narrative.py +182 -7
  195. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  196. package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
  197. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  198. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  199. package/runtime/python/okstra_ctl/run.py +67 -36
  200. package/runtime/python/okstra_ctl/run_context.py +10 -1
  201. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  202. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  203. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  204. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  205. package/runtime/python/okstra_ctl/task_query.py +239 -0
  206. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  207. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  208. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  209. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  210. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  211. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  212. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  213. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  214. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  215. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  216. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  217. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  218. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  219. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  220. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  221. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  222. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  223. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  224. package/runtime/python/okstra_project/__init__.py +2 -0
  225. package/runtime/python/okstra_project/dirs.py +18 -0
  226. package/runtime/python/okstra_project/state.py +45 -20
  227. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  228. package/runtime/python/okstra_token_usage/cli.py +23 -10
  229. package/runtime/python/okstra_token_usage/collect.py +25 -22
  230. package/runtime/python/okstra_token_usage/policy.py +193 -0
  231. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  232. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  233. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  234. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  235. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  236. package/runtime/schemas/record-secret-patterns.json +41 -0
  237. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  238. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  239. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  240. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  241. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  242. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  243. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  244. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  245. package/runtime/skills/okstra-code-review/SKILL.md +92 -136
  246. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  247. package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
  248. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  249. package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
  250. package/runtime/skills/okstra-manager/SKILL.md +31 -0
  251. package/runtime/skills/okstra-memory/SKILL.md +8 -1
  252. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  253. package/runtime/skills/okstra-run/SKILL.md +55 -183
  254. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  255. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  256. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  257. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  258. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  259. package/runtime/templates/implementation-worker-preamble.md +4 -9
  260. package/runtime/templates/manager/view.template.html +4 -0
  261. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  262. package/runtime/templates/trace/trace.template.md +42 -0
  263. package/runtime/templates/worker-prompt-preamble.md +4 -12
  264. package/runtime/validators/checks/fixtures-02.py +25 -33
  265. package/runtime/validators/validate-run.py +107 -38
@@ -0,0 +1,300 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ from collections.abc import Callable
5
+ from collections import defaultdict
6
+ from dataclasses import replace
7
+ from pathlib import Path
8
+ from stat import S_ISDIR
9
+
10
+ from okstra_project import StateError, parse_task_key
11
+
12
+ from ...json_boundary import JsonBoundaryError
13
+ from ...jsonl import parse_jsonl_snapshot
14
+ from ...manager_paths import (
15
+ ManagerPathError, canonical_manager_id, children_json_path,
16
+ directives_jsonl_path, journal_jsonl_path, manager_json_path, projects_json_path,
17
+ manager_root, snapshots_json_path, task_groups_root, task_manifest_path,
18
+ )
19
+ from ..config import SourceConfig, includes_project
20
+ from ..contracts import DoyouknowError, Node, Relation, SecretRefusal, canonical_json, record_secret_policy_digest
21
+ from ..source_contracts import PreparedSource, SourceDomain, SourceRef, SourceScan, SourceSnapshot, prepared_snapshot, validate_prepared_snapshot
22
+ from .io import read_source_object, read_source_text, safe_source_path
23
+
24
+
25
+ def _optional_object(home: Path, path: Path, default: dict) -> dict:
26
+ target = safe_source_path(home, path)
27
+ return read_source_object(home, target) if target.exists() else default
28
+
29
+
30
+ def _manager_manifest_candidates(home: Path, root: Path) -> tuple[Path, ...]:
31
+ groups = safe_source_path(home, task_groups_root(home, root.name))
32
+ try:
33
+ groups.stat()
34
+ except FileNotFoundError:
35
+ return ()
36
+ candidates = []
37
+ for group in sorted(groups.iterdir()):
38
+ if not S_ISDIR(safe_source_path(home, group).stat().st_mode):
39
+ continue
40
+ for task in sorted(group.iterdir()):
41
+ if S_ISDIR(safe_source_path(home, task).stat().st_mode):
42
+ candidates.append(task / "manifest.json")
43
+ return tuple(candidates)
44
+
45
+
46
+ def _project_rows(rows: object, settings: SourceConfig) -> list[dict]:
47
+ if not isinstance(rows, list) or any(not isinstance(row, dict) for row in rows):
48
+ raise DoyouknowError("manager project rows must be objects")
49
+ return [row for row in rows if not row.get("projectId") or includes_project(settings, row["projectId"])]
50
+
51
+
52
+ def _manager_projects(home: Path, root: Path, settings: SourceConfig) -> list[dict]:
53
+ payload = _optional_object(home, projects_json_path(home, root.name), {"projects": []})
54
+ rows = _project_rows(payload.get("projects"), settings)
55
+ for row in rows:
56
+ if not isinstance(row.get("projectId"), str) or not row["projectId"] or not isinstance(row.get("projectRoot"), str) or not row["projectRoot"]:
57
+ raise DoyouknowError("manager project registration is invalid")
58
+ return rows
59
+
60
+
61
+ JOURNAL_NATIVE_ID = "journal"
62
+
63
+
64
+ def _optional_jsonl(home: Path, path: Path) -> tuple[list[dict], list[int]]:
65
+ """Rows and damaged line numbers of an optional JSONL source file."""
66
+ target = safe_source_path(home, path)
67
+ return parse_jsonl_snapshot(read_source_text(home, target)) if target.exists() else ([], [])
68
+
69
+
70
+ def _root_snapshot(home: Path, manager: dict, projects: list[dict], settings: SourceConfig) -> SourceSnapshot:
71
+ manager_id = manager["managerId"]
72
+ metadata = {"manager": manager, "projects": projects}
73
+ nodes = tuple({"kind": "project", "scope": "okstra-project", "key": row["projectId"], "ref": f"project-{index}", "title": row["projectId"]} for index, row in enumerate(projects))
74
+ relations = tuple({"from": "$source", "to": node["ref"], "kind": "includes-project", "reason": "The manager registers this project.", "evidence": [str(projects_json_path(home, manager_id))], "standing": "observed"} for node in nodes)
75
+ snapshot = SourceSnapshot(
76
+ SourceRef("manager", manager_id, "$manager"),
77
+ {"kind": "entity", "scope": "okstra-manager", "key": manager_id, "ref": "primary", "title": manager_id},
78
+ str(manager_json_path(home, manager_id)), metadata, nodes, relations,
79
+ source_updated_at=manager.get("updatedAt"), scope=settings["scope"],
80
+ )
81
+ return snapshot
82
+
83
+
84
+ def _task_records(home: Path, manager_id: str, group: str, task_id: str, settings: SourceConfig) -> tuple[list[dict], list[dict], dict]:
85
+ children = _project_rows(read_source_object(home, children_json_path(home, manager_id, group, task_id)).get("children"), settings)
86
+ saved = _optional_object(home, snapshots_json_path(home, manager_id, group, task_id), {})
87
+ saved = {**saved, "children": _project_rows(saved.get("children", []), settings)}
88
+ directives, damaged = _optional_jsonl(home, directives_jsonl_path(home, manager_id, group, task_id))
89
+ if damaged:
90
+ raise DoyouknowError("manager notes contain damaged rows")
91
+ return children, _project_rows(directives, settings), saved
92
+
93
+
94
+ def _child_graph(children: list[dict], linked: set[str], evidence: Path) -> tuple[list[Node], list[Relation], list[dict]]:
95
+ nodes: list[Node] = []
96
+ relations: list[Relation] = []
97
+ kept_children = []
98
+ for index, child in enumerate(children):
99
+ key, project_id = child.get("taskKey"), child.get("projectId")
100
+ if not isinstance(key, str) or not isinstance(project_id, str) or parse_task_key(key) != (project_id, child.get("taskGroup"), child.get("taskId")):
101
+ raise DoyouknowError("manager child identity is invalid")
102
+ ref = f"child-{index}"
103
+ nodes.append({"kind": "task", "scope": project_id, "key": key, "ref": ref, "title": child["taskId"]})
104
+ relations.append({"from": "$source", "to": ref, "kind": "assigns-task" if project_id in linked else "references-unlinked-task", "reason": "The manager lists this child task.", "evidence": [str(evidence)], "standing": "observed"})
105
+ kept_children.append({**child, "projectLinked": project_id in linked})
106
+ return nodes, relations, kept_children
107
+
108
+
109
+ def _task_snapshot(home: Path, path: Path, manifest: dict, ref: SourceRef, projects: list[dict], settings: SourceConfig) -> SourceSnapshot:
110
+ group, task_id = manifest["taskGroup"], manifest["taskId"]
111
+ manager_id = ref.owner_id
112
+ if manifest.get("managerId") != manager_id or path.resolve() != task_manifest_path(home, manager_id, group, task_id).resolve():
113
+ raise DoyouknowError("manager task identity does not match its source")
114
+ children, directives, saved = _task_records(home, manager_id, group, task_id, settings)
115
+ child_nodes, child_relations, kept_children = _child_graph(children, {row["projectId"] for row in projects}, children_json_path(home, manager_id, group, task_id))
116
+ nodes = ({"kind": "entity", "scope": "okstra-manager", "key": manager_id, "ref": "manager", "title": manager_id}, *child_nodes)
117
+ relations = ({"from": "$source", "to": "manager", "kind": "belongs-to", "reason": "The manager owns this task.", "evidence": [str(path)], "standing": "observed"}, *child_relations)
118
+ snapshot = SourceSnapshot(
119
+ ref,
120
+ {"kind": "task", "scope": "manager:" + manager_id, "key": ref.native_id, "ref": "primary", "title": task_id},
121
+ str(path), {"manifest": manifest, "children": kept_children, "notes": directives, "snapshot": saved},
122
+ nodes, relations, source_updated_at=manifest.get("updatedAt"), scope=settings["scope"],
123
+ )
124
+ return snapshot
125
+
126
+
127
+ def _journal_source(home: Path, manager_id: str, settings: SourceConfig) -> tuple[SourceRef | None, SourceSnapshot | None, str | None]:
128
+ """The manager journal as its own source, so its damage or size cannot stop the root and task sources."""
129
+ path = journal_jsonl_path(home, manager_id)
130
+ if not safe_source_path(home, path).exists():
131
+ return None, None, None
132
+ ref = SourceRef("manager", manager_id, JOURNAL_NATIVE_ID)
133
+ try:
134
+ rows, damaged = _optional_jsonl(home, path)
135
+ except (DoyouknowError, JsonBoundaryError, OSError):
136
+ return ref, None, "manager-journal-unavailable"
137
+ if damaged:
138
+ return ref, None, "manager-journal-damaged"
139
+ snapshot = SourceSnapshot(
140
+ ref,
141
+ {"kind": "entity", "scope": "manager:" + manager_id, "key": JOURNAL_NATIVE_ID, "ref": "primary", "title": "Manager journal"},
142
+ str(path), {"journal": rows},
143
+ ({"kind": "entity", "scope": "okstra-manager", "key": manager_id, "ref": "manager", "title": manager_id},),
144
+ ({"from": "$source", "to": "manager", "kind": "belongs-to", "reason": "The manager owns this journal.", "evidence": [str(path)], "standing": "observed"},),
145
+ scope=settings["scope"],
146
+ )
147
+ return ref, snapshot, None
148
+
149
+
150
+ def _snapshot_error(snapshot: SourceSnapshot) -> str:
151
+ return "manager-journal-unavailable" if snapshot.ref.native_id == JOURNAL_NATIVE_ID else "manager-task-unavailable"
152
+
153
+
154
+ def _manager_manifest_data(home: Path, path: Path) -> dict:
155
+ manifest = read_source_object(home, path)
156
+ group, task_id = manifest.get("taskGroup"), manifest.get("taskId")
157
+ if not isinstance(group, str) or not group or not isinstance(task_id, str) or not task_id:
158
+ raise DoyouknowError("manager task identity is missing")
159
+ return manifest
160
+
161
+
162
+ def _validate_manager_snapshot(snapshot: SourceSnapshot, gate: Callable[[PreparedSource], bool] | None) -> None:
163
+ prepared = prepared_snapshot(snapshot)
164
+ if gate is not None:
165
+ if not gate(prepared):
166
+ raise SecretRefusal("manager source refused")
167
+ else:
168
+ validate_prepared_snapshot(prepared)
169
+
170
+
171
+ def _manager_task_source(home: Path, path: Path, manager_id: str, projects: list[dict], settings: SourceConfig) -> tuple[SourceRef | None, SourceSnapshot | None, str | None]:
172
+ ref = None
173
+ try:
174
+ manifest = _manager_manifest_data(home, path)
175
+ ref = SourceRef("manager", manager_id, "task:" + canonical_json([manifest["taskGroup"], manifest["taskId"]]))
176
+ snapshot = _task_snapshot(home, path, manifest, ref, projects, settings)
177
+ return ref, snapshot, None
178
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
179
+ return ref, None, "manager-task-unavailable"
180
+
181
+
182
+ def _scan_manager(home: Path, root: Path, settings: SourceConfig, *, validate: bool = True, gate: Callable[[PreparedSource], bool] | None = None) -> tuple[SourceScan, list[dict]]:
183
+ manager_id = root.name
184
+ domain = SourceDomain("manager", manager_id)
185
+ snapshots, observed, errors = [], [], []
186
+ try:
187
+ canonical_manager_id(manager_id)
188
+ manager = read_source_object(home, manager_json_path(home, manager_id))
189
+ if manager.get("managerId") != manager_id:
190
+ raise DoyouknowError("manager identity does not match its source")
191
+ projects = _manager_projects(home, root, settings)
192
+ root_snapshot = _root_snapshot(home, manager, projects, settings)
193
+ snapshots.append(root_snapshot)
194
+ observed.append(SourceRef("manager", manager_id, "$manager"))
195
+ child_sources = [_manager_task_source(home, path, manager_id, projects, settings)
196
+ for path in _manager_manifest_candidates(home, root)]
197
+ child_sources.append(_journal_source(home, manager_id, settings))
198
+ for ref, snapshot, error in child_sources:
199
+ if ref is not None:
200
+ observed.append(ref)
201
+ if snapshot is not None:
202
+ snapshots.append(snapshot)
203
+ elif error is not None:
204
+ errors.append(error)
205
+ except (DoyouknowError, JsonBoundaryError, ManagerPathError, OSError, StateError, TypeError, RecursionError):
206
+ return SourceScan(domain, (), (), "unavailable", ("manager-source-unavailable",)), []
207
+ scan = SourceScan(domain, tuple(snapshots), tuple(observed), "partial" if errors else "complete", tuple(errors))
208
+ checked = gate_manager_scan(scan, gate=gate) if validate else scan
209
+ return checked, [] if checked.status == "unavailable" else projects
210
+
211
+
212
+ def gate_manager_scan(scan: SourceScan, *, gate: Callable[[PreparedSource], bool] | None = None) -> SourceScan:
213
+ if scan.status == "unavailable":
214
+ return scan
215
+ root = next((snapshot for snapshot in scan.snapshots if snapshot.ref.native_id == "$manager"), None)
216
+ try:
217
+ if root is None:
218
+ raise DoyouknowError("manager root is unavailable")
219
+ _validate_manager_snapshot(root, gate)
220
+ except SecretRefusal:
221
+ return replace(scan, snapshots=(), status="unavailable", errors=("manager-secret-refused",))
222
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
223
+ return replace(scan, snapshots=(), status="unavailable", errors=("manager-source-unavailable",))
224
+ snapshots = [root]
225
+ errors = list(scan.errors)
226
+ for snapshot in scan.snapshots:
227
+ if snapshot is root:
228
+ continue
229
+ try:
230
+ _validate_manager_snapshot(snapshot, gate)
231
+ snapshots.append(snapshot)
232
+ except SecretRefusal:
233
+ errors.append("manager-secret-refused")
234
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
235
+ errors.append(_snapshot_error(snapshot))
236
+ return replace(scan, snapshots=tuple(snapshots), status="partial" if errors else scan.status, errors=tuple(errors))
237
+
238
+
239
+ def _manager_source_paths(home: Path, root: Path) -> list[tuple[Path, bool]]:
240
+ manager_id = root.name
241
+ paths = [(manager_json_path(home, manager_id), True), (projects_json_path(home, manager_id), False),
242
+ (journal_jsonl_path(home, manager_id), False)]
243
+ for path in _manager_manifest_candidates(home, root):
244
+ manifest = _manager_manifest_data(home, path)
245
+ group, task_id = manifest["taskGroup"], manifest["taskId"]
246
+ paths.extend((
247
+ (path, True),
248
+ (children_json_path(home, manager_id, group, task_id), True),
249
+ (snapshots_json_path(home, manager_id, group, task_id), False),
250
+ (directives_jsonl_path(home, manager_id, group, task_id), False),
251
+ ))
252
+ return sorted(paths, key=lambda item: str(item[0]))
253
+
254
+
255
+ def _manager_source_fingerprint(home: Path, root: Path, settings: SourceConfig) -> str:
256
+ projection = {key: settings[key] for key in ("scope", "includeProjects", "excludeProjects")}
257
+ digest = hashlib.sha256(canonical_json([projection, record_secret_policy_digest()]).encode("utf-8"))
258
+ for path, required in _manager_source_paths(home, root):
259
+ target = safe_source_path(home, path)
260
+ body_digest = None
261
+ if required or target.exists():
262
+ body_digest = hashlib.sha256(read_source_text(home, target).encode("utf-8")).hexdigest()
263
+ digest.update(canonical_json([str(path.relative_to(root)), body_digest]).encode("utf-8"))
264
+ return digest.hexdigest()
265
+
266
+
267
+ def prepare_manager_source(home: Path, manager_id: str, settings: SourceConfig) -> PreparedSource:
268
+ ref = SourceRef("manager", manager_id, "$manager")
269
+ if "manager" not in settings["sources"]:
270
+ return PreparedSource(ref, None, outcome="excluded")
271
+ try:
272
+ root = manager_root(home, manager_id)
273
+ before = _manager_source_fingerprint(home, root, settings)
274
+ scan, _ = _scan_manager(home, root, settings, validate=False)
275
+ after = _manager_source_fingerprint(home, root, settings)
276
+ if scan.status == "unavailable" or before != after:
277
+ return PreparedSource(ref, None, outcome="unavailable", error_code="manager-source-unavailable")
278
+ return PreparedSource(ref, before, scan=scan)
279
+ except (DoyouknowError, JsonBoundaryError, ManagerPathError, OSError, StateError, TypeError, RecursionError):
280
+ return PreparedSource(ref, None, outcome="unavailable", error_code="manager-source-unavailable")
281
+
282
+
283
+ def scan_managers(home: Path, settings: SourceConfig, *, gate: Callable[[PreparedSource], bool] | None = None) -> tuple[tuple[SourceScan, ...], dict[str, tuple[Path, ...]]]:
284
+ scans, projects = [], defaultdict(set)
285
+ if not {"manager", "task"}.intersection(settings["sources"]):
286
+ return (), {}
287
+ try:
288
+ base = safe_source_path(home, "managers")
289
+ roots = sorted(path for path in base.iterdir() if path.is_dir()) if base.exists() else []
290
+ for root in roots:
291
+ if "manager" in settings["sources"]:
292
+ scan, entries = _scan_manager(home, root, settings, gate=gate)
293
+ scans.append(scan)
294
+ else:
295
+ entries = _manager_projects(home, root, settings)
296
+ for entry in entries:
297
+ projects[entry["projectId"]].add(Path(entry["projectRoot"]).resolve())
298
+ except (DoyouknowError, JsonBoundaryError, OSError, TypeError, RecursionError):
299
+ scans.append(SourceScan(SourceDomain("manager", "$discovery"), (), (), "unavailable", ("manager-discovery-unavailable",)))
300
+ return tuple(scans), {key: tuple(sorted(paths)) for key, paths in projects.items()}
@@ -0,0 +1,179 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from collections.abc import Callable
5
+ from typing import TypedDict, cast
6
+
7
+ from ...json_boundary import JsonBoundaryError
8
+ from ...jsonl import parse_jsonl_snapshot
9
+ from ..config import SourceConfig, includes_group, includes_project
10
+ from ..contracts import DoyouknowError, Node, Relation, SecretRefusal, asset_object, canonical_json, record_secret_policy_digest
11
+ from ..identity import stable_id
12
+ from ..source_contracts import JsonValue, PreparedSource, SourceDomain, SourceRef, SourceScan, SourceSnapshot, validate_prepared_snapshot
13
+ from .io import read_source_text, safe_source_path
14
+
15
+ MAX_MEMORY_ROWS = 10_000
16
+ MAX_MEMORY_BODY_PREVIEW_CHARS = 1000
17
+ MEMORY_DOMAIN = SourceDomain("memory", "memory-book")
18
+
19
+
20
+ class MemoryEntry(TypedDict):
21
+ id: str
22
+ title: str
23
+ type: str
24
+ projectGroup: str
25
+ source: str
26
+ tags: list[str]
27
+ relatedProjects: list[str]
28
+ status: str
29
+ createdAt: str
30
+ archivedAt: str | None
31
+ path: str
32
+
33
+
34
+ class MemoryEntryContract(TypedDict):
35
+ schemaVersion: int
36
+ requiredStrings: list[str]
37
+ stringArrays: list[str]
38
+ nullableStrings: list[str]
39
+ optionalStrings: list[str]
40
+ enums: dict[str, list[str]]
41
+
42
+
43
+ def _memory_entry_contract() -> MemoryEntryContract:
44
+ contract = asset_object("memory-entry-contract-v1.json")
45
+ lists = ("requiredStrings", "stringArrays", "nullableStrings", "optionalStrings")
46
+ if type(contract.get("schemaVersion")) is not int or contract["schemaVersion"] != 1 or any(not isinstance(contract.get(key), list) or any(not isinstance(item, str) for item in contract[key]) for key in lists):
47
+ raise DoyouknowError("invalid Memory Book entry contract")
48
+ enums = contract.get("enums")
49
+ if not isinstance(enums, dict) or not {"type", "status"} <= enums.keys() or any(not isinstance(items, list) or not items or any(not isinstance(item, str) for item in items) for items in enums.values()):
50
+ raise DoyouknowError("invalid Memory Book entry contract")
51
+ return cast(MemoryEntryContract, contract)
52
+
53
+
54
+ def _is_memory_entry(row: dict, contract: MemoryEntryContract) -> bool:
55
+ return (
56
+ all(isinstance(row.get(key), str) for key in contract["requiredStrings"])
57
+ and all(isinstance(row.get(key), list) and all(isinstance(item, str) for item in row[key]) for key in contract["stringArrays"])
58
+ and all(key in row and (row[key] is None or isinstance(row[key], str)) for key in contract["nullableStrings"])
59
+ and all(key not in row or isinstance(row[key], str) for key in contract["optionalStrings"])
60
+ and all(isinstance(row.get(key), str) and row[key] in items for key, items in contract["enums"].items())
61
+ )
62
+
63
+
64
+ def _includes_memory_entry(entry: MemoryEntry, settings: SourceConfig) -> bool:
65
+ return (
66
+ includes_group(settings, entry["projectGroup"])
67
+ and (not settings["includeProjects"] or bool(entry["relatedProjects"]))
68
+ and all(includes_project(settings, project) for project in entry["relatedProjects"])
69
+ )
70
+
71
+
72
+ def _memory_snapshot(root: Path, entry: MemoryEntry, settings: SourceConfig, body: str) -> SourceSnapshot:
73
+ locator = safe_source_path(root, entry["path"]).as_uri()
74
+ projects = tuple(dict.fromkeys(entry["relatedProjects"]))
75
+ nodes: tuple[Node, ...] = tuple(
76
+ {"kind": "project", "scope": "okstra-project", "key": project, "title": project, "ref": f"project:{project}"}
77
+ for project in projects
78
+ )
79
+ relations: tuple[Relation, ...] = tuple(
80
+ {"from": "$source", "to": f"project:{project}", "kind": "related-project",
81
+ "reason": "Memory entry names this related project.", "evidence": [locator], "standing": "observed"}
82
+ for project in projects
83
+ )
84
+ metadata: dict[str, JsonValue] = {
85
+ **entry, "bodyPreview": body[:MAX_MEMORY_BODY_PREVIEW_CHARS],
86
+ "bodyTruncated": len(body) > MAX_MEMORY_BODY_PREVIEW_CHARS,
87
+ "bodyDigest": stable_id("memory-body", body),
88
+ }
89
+ snapshot = SourceSnapshot(
90
+ SourceRef("memory", "memory-book", entry["id"]),
91
+ {"kind": "artifact", "scope": "memory-book", "key": entry["id"], "title": entry["title"]},
92
+ locator, metadata, nodes=nodes, relations=relations,
93
+ lifecycle="archived" if entry["status"] == "archived" else "active",
94
+ source_updated_at=entry["archivedAt"] or entry["createdAt"], scope=settings["scope"],
95
+ )
96
+ return snapshot
97
+
98
+
99
+ def read_memory_source(home: Path, ref: SourceRef, settings: SourceConfig) -> PreparedSource:
100
+ try:
101
+ if ref.kind != "memory" or ref.owner_id != "memory-book":
102
+ raise DoyouknowError("memory reference has a different owner")
103
+ root = safe_source_path(home, "memory-book")
104
+ rows, damaged = parse_jsonl_snapshot(read_source_text(root, "index.jsonl"))
105
+ if len(rows) > MAX_MEMORY_ROWS:
106
+ raise DoyouknowError("memory index exceeds row limit")
107
+ selected = [row for row in rows if row.get("id") == ref.native_id]
108
+ contract = _memory_entry_contract()
109
+ if len(selected) != 1 or not _is_memory_entry(selected[0], contract):
110
+ raise DoyouknowError("memory reference is unavailable")
111
+ entry = cast(MemoryEntry, selected[0])
112
+ if not _includes_memory_entry(entry, settings):
113
+ return PreparedSource(ref, None, outcome="excluded")
114
+ body = read_source_text(root, entry["path"])
115
+ return _prepare_memory_snapshot(root, entry, settings, body, contract)
116
+ except (OSError, UnicodeError, DoyouknowError, JsonBoundaryError, RecursionError):
117
+ return PreparedSource(ref, None, outcome="unavailable", error_code="memory-source-unavailable")
118
+
119
+
120
+ def _prepare_memory_snapshot(root: Path, entry: MemoryEntry, settings: SourceConfig, body: str, contract: MemoryEntryContract) -> PreparedSource:
121
+ snapshot = _memory_snapshot(root, entry, settings, body)
122
+ fingerprint = stable_id("memory-registration", canonical_json(entry), snapshot.metadata["bodyDigest"], canonical_json(contract), canonical_json(settings["scope"]), record_secret_policy_digest())
123
+ return PreparedSource(snapshot.ref, fingerprint, snapshot, secret_texts=(body,))
124
+
125
+
126
+ def _memory_projection(root: Path, entry: MemoryEntry, settings: SourceConfig, contract: MemoryEntryContract, gate: Callable[[PreparedSource], bool] | None) -> tuple[SourceSnapshot | None, str | None]:
127
+ try:
128
+ body = read_source_text(root, entry["path"])
129
+ except (OSError, UnicodeError, DoyouknowError):
130
+ return None, "memory-body-unreadable"
131
+ try:
132
+ prepared = _prepare_memory_snapshot(root, entry, settings, body, contract)
133
+ if gate is not None:
134
+ if not gate(prepared):
135
+ return None, "memory-secret-refused"
136
+ else:
137
+ validate_prepared_snapshot(prepared)
138
+ return prepared.snapshot, None
139
+ except SecretRefusal:
140
+ return None, "memory-secret-refused"
141
+ except (OSError, UnicodeError, DoyouknowError, JsonBoundaryError):
142
+ return None, "memory-projection-unavailable"
143
+
144
+
145
+ def scan_memory_sources(home: Path, settings: SourceConfig, *, gate: Callable[[PreparedSource], bool] | None = None) -> SourceScan:
146
+ try:
147
+ root = safe_source_path(home, "memory-book")
148
+ if not root.exists():
149
+ return SourceScan(MEMORY_DOMAIN, (), (), "complete")
150
+ rows, invalid_lines = parse_jsonl_snapshot(read_source_text(root, "index.jsonl"))
151
+ except (OSError, UnicodeError, DoyouknowError):
152
+ return SourceScan(MEMORY_DOMAIN, (), (), "partial", ("memory-index-unreadable",))
153
+ try:
154
+ contract = _memory_entry_contract()
155
+ except (OSError, DoyouknowError, JsonBoundaryError):
156
+ return SourceScan(MEMORY_DOMAIN, (), (), "unavailable", ("memory-contract-unavailable",))
157
+ errors = [f"memory-index-invalid-line:{number}" for number in invalid_lines]
158
+ if len(rows) > MAX_MEMORY_ROWS:
159
+ errors.append("memory-index-row-limit")
160
+ snapshots: list[SourceSnapshot] = []
161
+ observed: dict[str, SourceRef] = {}
162
+ for row in rows[:MAX_MEMORY_ROWS]:
163
+ if not _is_memory_entry(row, contract) or not isinstance(row.get("id"), str) or not row["id"].strip():
164
+ errors.append("memory-index-invalid-entry")
165
+ continue
166
+ entry = cast(MemoryEntry, row)
167
+ if entry["id"] in observed:
168
+ errors.append("memory-index-duplicate-entry")
169
+ continue
170
+ observed[entry["id"]] = SourceRef("memory", "memory-book", entry["id"])
171
+ if not _includes_memory_entry(entry, settings):
172
+ continue
173
+ snapshot, error = _memory_projection(root, entry, settings, contract, gate)
174
+ if snapshot is not None:
175
+ snapshots.append(snapshot)
176
+ if error is not None:
177
+ errors.append(error)
178
+ return SourceScan(MEMORY_DOMAIN, tuple(snapshots), tuple(observed.values()),
179
+ "partial" if errors else "complete", tuple(errors))
@@ -0,0 +1,95 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from okstra_project import StateError, parse_task_key, resolve_task_root_read_only
6
+ from okstra_project.dirs import PROJECT_JSON_RELATIVE, TASK_CATALOG_RELATIVE, TASK_MANIFEST_FILENAME, TASKS_RELATIVE
7
+ from okstra_project.state import derived_task_status
8
+
9
+ from ...json_boundary import JsonBoundaryError
10
+ from ..config import SourceConfig, includes_project
11
+ from ..contracts import DoyouknowError
12
+ from ..source_contracts import SourceDomain, SourceRef, SourceScan, SourceSnapshot, snapshot_payload
13
+ from .io import read_source_object, safe_source_path
14
+
15
+
16
+ def _task_snapshot(project_root: Path, project_id: str, task_key: str, catalog: list[dict], settings: SourceConfig) -> SourceSnapshot:
17
+ task_root = resolve_task_root_read_only(project_root, task_key, catalog=catalog)
18
+ if task_root is None:
19
+ raise DoyouknowError("project task is unavailable")
20
+ task_root = safe_source_path(project_root, task_root)
21
+ manifest_path = task_root / TASK_MANIFEST_FILENAME
22
+ manifest = read_source_object(project_root, manifest_path)
23
+ if manifest.get("projectId") != project_id or manifest.get("taskKey") != task_key:
24
+ raise DoyouknowError("project task identity does not match its source")
25
+ _, group, task_id = parse_task_key(task_key)
26
+ if manifest.get("taskGroup") != group or manifest.get("taskId") != task_id:
27
+ raise DoyouknowError("project task identity is inconsistent")
28
+ direct = manifest.get("latestWorkRecordPath")
29
+ metadata = {"projectId": project_id, "manifest": manifest, "status": derived_task_status(manifest)}
30
+ if direct:
31
+ path = safe_source_path(project_root, direct)
32
+ safe_source_path(task_root, path)
33
+ record = read_source_object(project_root, path)
34
+ if record.get("taskKey") != task_key:
35
+ raise DoyouknowError("direct work identity does not match its source")
36
+ metadata["directWork"] = record
37
+ project_node = {"kind": "project", "scope": "okstra-project", "key": project_id, "title": project_id, "ref": "project"}
38
+ snapshot = SourceSnapshot(
39
+ ref=SourceRef("task", project_id, task_key),
40
+ primary_node={"kind": "task", "scope": project_id, "key": task_key, "ref": "primary", "title": str(manifest.get("title") or task_id)},
41
+ locator=str(manifest_path), metadata=metadata, nodes=(project_node,),
42
+ relations=({"from": "$source", "to": "project", "kind": "belongs-to", "reason": "The project owns this task.", "evidence": [str(manifest_path)], "standing": "observed"},),
43
+ source_updated_at=manifest.get("workStatusUpdatedAt") or manifest.get("updatedAt"), scope=settings["scope"],
44
+ )
45
+ snapshot_payload(snapshot)
46
+ return snapshot
47
+
48
+
49
+ def _task_catalog(project_root: Path) -> list[dict] | None:
50
+ catalog_path = safe_source_path(project_root, TASK_CATALOG_RELATIVE)
51
+ try:
52
+ catalog_path.stat()
53
+ except FileNotFoundError:
54
+ try:
55
+ safe_source_path(project_root, TASKS_RELATIVE).stat()
56
+ except FileNotFoundError:
57
+ return None
58
+ catalog = read_source_object(project_root, catalog_path).get("tasks")
59
+ if not isinstance(catalog, list) or any(not isinstance(row, dict) for row in catalog):
60
+ raise DoyouknowError("project task catalog is invalid")
61
+ return catalog
62
+
63
+
64
+ def _catalog_task_key(row: dict, project_id: str) -> str:
65
+ task_key = row.get("taskKey", "")
66
+ if not isinstance(task_key, str):
67
+ raise DoyouknowError("project task key must be a string")
68
+ owner, _, _ = parse_task_key(task_key)
69
+ if owner != project_id:
70
+ raise DoyouknowError("project catalog identity does not match its source")
71
+ return task_key
72
+
73
+
74
+ def scan_project_tasks(project_root: Path, project_id: str, settings: SourceConfig) -> SourceScan:
75
+ domain = SourceDomain("task", project_id)
76
+ if "task" not in settings["sources"] or not includes_project(settings, project_id):
77
+ return SourceScan(domain, (), (), "partial")
78
+ snapshots, observed, errors = [], [], []
79
+ try:
80
+ project = read_source_object(project_root, PROJECT_JSON_RELATIVE)
81
+ if project.get("projectId") != project_id:
82
+ raise DoyouknowError("registered project identity does not match its source")
83
+ catalog = _task_catalog(project_root)
84
+ if catalog is None:
85
+ return SourceScan(domain, (), (), "complete")
86
+ for row in catalog:
87
+ try:
88
+ task_key = _catalog_task_key(row, project_id)
89
+ observed.append(SourceRef("task", project_id, task_key))
90
+ snapshots.append(_task_snapshot(project_root, project_id, task_key, catalog, settings))
91
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
92
+ errors.append("task-source-unavailable")
93
+ except (DoyouknowError, JsonBoundaryError, OSError, StateError, TypeError, RecursionError):
94
+ return SourceScan(domain, (), (), "unavailable", ("project-source-unavailable",))
95
+ return SourceScan(domain, tuple(snapshots), tuple(observed), "partial" if errors else "complete", tuple(errors))