okstra 0.231.0 → 0.232.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 (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -0,0 +1,297 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import re
5
+ from pathlib import Path
6
+ from collections.abc import Mapping
7
+ from typing import Any
8
+
9
+ from .agent.invocation import (
10
+ reserved_generation_reference, reserved_invocation_metadata_path, verify_agent_invocation,
11
+ )
12
+ from .attempt_evidence import AttemptEvidenceSeal, read_sealed_artifact
13
+ from .conformance_evidence import BoundInvocation, bound_attempt, evidence_read_errors, load_run_verifiers
14
+ from .design_review import parse_design_review
15
+ from .execution_identity import ExecutionManifest, build_dispatch_id
16
+ from .execution_manifest import read_execution_manifest
17
+ from .json_boundary import load_owned_object
18
+ from .qa_procedures import canonical_json_digest, content_digest, safe_qa_path
19
+ from .verification_dispatch import verification_generation_number
20
+ from .verification_input_ref import VerificationInputReference
21
+ from .verification_inputs import read_verification_inputs
22
+ from .verification_input_types import DESIGN_REVIEW_INPUT_SCHEMA_VERSION
23
+ from .verification_invocation import VerificationGenerationReference, read_invocation_generation
24
+ from .verification_evidence import roster_verifier_role_execution_ref
25
+
26
+
27
+ def design_review_required(project: Path, manifest: Mapping[str, Any]) -> bool:
28
+ reference = VerificationInputReference.from_artifact_fields(manifest)
29
+ if reference is None or manifest.get("taskType") not in ("implementation", "final-verification"):
30
+ return False
31
+ inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
32
+ return inputs["schemaVersion"] == DESIGN_REVIEW_INPUT_SCHEMA_VERSION
33
+
34
+
35
+ def collect_design_reviews(project: Path, manifest_path: Path) -> dict[str, dict[str, Any]]:
36
+ with evidence_read_errors():
37
+ manifest = load_owned_object(manifest_path, artifact="run manifest")
38
+ if manifest.get("taskType") != "implementation" or not design_review_required(project, manifest):
39
+ return {}
40
+ run = load_run_verifiers(project, manifest_path)
41
+ execution = read_execution_manifest(manifest_path)
42
+ generation = max((verification_generation_number(row.dispatch_kind)
43
+ for row in execution.invocations
44
+ if row.duty_id in ("implementation-executor", "implementation-verifier")), default=1)
45
+ roster = [row["workerId"] for row in manifest.get("workerAssignments", [])
46
+ if row.get("role") == "verifier"]
47
+ if not roster or len(set(roster)) != len(roster):
48
+ raise ValueError("design review requires a distinct verifier roster")
49
+ reviews = {}
50
+ for worker in roster:
51
+ role = roster_verifier_role_execution_ref(manifest, worker)
52
+ current = bound_attempt(run, role, generation)
53
+ before = (generation, len(execution.invocations), 2**31)
54
+ if current is not None:
55
+ before = (generation, current[0].index, current[1])
56
+ history = _prior_reviews(project, manifest_path, manifest, execution, role, before)
57
+ current_attempt = None if current is None else next((row for row in execution.attempts
58
+ if (row.invocation_ref, row.attempt) == (current[0].invocation.invocation_ref, current[1])), None)
59
+ if current_attempt is None or current_attempt.status != "ok":
60
+ reviews[worker] = {"collection": "incomplete", "reason": "no current bound verifier attempt",
61
+ "generationNumber": generation, "verdict": "not-run", "history": history}
62
+ continue
63
+ record, body = _read_review(project, manifest_path, manifest, execution, *current)
64
+ record["history"] = history
65
+ record["carry"] = _read_carry(body, history)
66
+ if any(row["disposition"] == "open" for row in record["carry"]):
67
+ record["verdict"] = "FAIL"
68
+ reviews[worker] = record
69
+ return reviews
70
+
71
+
72
+ def _prior_reviews(
73
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
74
+ role: str, before: tuple[int, int, int],
75
+ ) -> list[dict[str, Any]]:
76
+ history = []
77
+ for index, invocation in enumerate(execution.invocations):
78
+ if invocation.role_execution_ref != role or invocation.duty_id != "implementation-verifier":
79
+ continue
80
+ number = verification_generation_number(invocation.dispatch_kind)
81
+ for attempt in execution.attempts:
82
+ if (attempt.invocation_ref != invocation.invocation_ref or attempt.status != "ok"
83
+ or (number, index, attempt.attempt) >= before):
84
+ continue
85
+ reference = reserved_generation_reference(project, manifest, invocation.invocation_ref, attempt.attempt)
86
+ if reference is None:
87
+ raise ValueError("earlier design-review attempt has no bound generation")
88
+ binding = BoundInvocation(invocation, number, index, None, reference.to_payload())
89
+ record, _ = _read_review(project, manifest_path, manifest, execution, binding, attempt.attempt)
90
+ history.append(record)
91
+ return history
92
+
93
+
94
+ def prior_design_review_prompt(
95
+ project: Path, manifest_path: Path, role: str, generation: int,
96
+ invocation_ref: str = "", attempt: int = 1,
97
+ ) -> str:
98
+ run = load_run_verifiers(project, manifest_path)
99
+ execution = read_execution_manifest(manifest_path)
100
+ index = next((index for index, row in enumerate(execution.invocations)
101
+ if row.invocation_ref == invocation_ref), len(execution.invocations))
102
+ history = _prior_reviews(project, manifest_path, run.manifest,
103
+ execution, role, (generation, index, attempt))
104
+ if not history:
105
+ return ""
106
+ return ("\n## Prior Design Review Findings\n\n"
107
+ "The current census requires fresh inspection of the full stage diff. Earlier findings "
108
+ "are retained below; do not inherit their rule judgments. Return `## Design Carry` "
109
+ "with a JSON array containing {finding, disposition, basis} for each earlier blocking "
110
+ "finding, where finding is `<generationNumber>:<invocationRef>:<attempt>:<id>`, disposition is "
111
+ "open/fixed/accepted-risk/rejected, and basis cites the current code/test or an explicit "
112
+ "accepted-risk decision. Preserve that basis for every disposition.\n\n"
113
+ + json.dumps(history, ensure_ascii=False, indent=2) + "\n")
114
+
115
+
116
+ def _read_review(
117
+ project: Path, manifest_path: Path, manifest: Mapping[str, Any], execution: ExecutionManifest,
118
+ binding: BoundInvocation, attempt: int,
119
+ ) -> tuple[dict[str, Any], str]:
120
+ invocation = binding.invocation
121
+ metadata_path = reserved_invocation_metadata_path(project, manifest, invocation.invocation_ref, attempt)
122
+ if metadata_path is None:
123
+ raise ValueError("design review has no reserved invocation metadata")
124
+ errors = verify_agent_invocation(
125
+ metadata_path, project_root=project, expected_run_manifest_path=manifest_path,
126
+ expected_audience="implementation-verifier", expected_invocation_ref=invocation.invocation_ref,
127
+ expected_role_execution_ref=invocation.role_execution_ref,
128
+ expected_participant_ref=invocation.participant_ref,
129
+ )
130
+ if errors:
131
+ raise ValueError("design review invocation: " + "; ".join(errors))
132
+ generation = read_invocation_generation(project, manifest_path, manifest,
133
+ VerificationGenerationReference.from_payload(binding.generation_ref),
134
+ "implementation-verifier")
135
+ if generation is None or "designReview" not in generation:
136
+ raise ValueError("design review has no sealed census")
137
+ from .paths import RunRef
138
+
139
+ expected_path = RunRef.from_manifest(manifest_path, manifest).verification_generation(binding.generation_number)
140
+ if (generation["generation"] != binding.generation_number
141
+ or binding.generation_ref["path"] != expected_path.relative_to(project).as_posix()):
142
+ raise ValueError("design review generation differs from its dispatch")
143
+ result_path, raw = _read_attempt_result(project, execution, invocation.invocation_ref, attempt)
144
+ body = raw.decode("utf-8")
145
+ source = Path(generation["sourceRoot"])
146
+ review = parse_design_review(source if source.is_dir() else project, generation["designReview"], body)
147
+ verdicts = re.findall(r"^Verifier verdict: (PASS|CONCERNS|FAIL)$", body, re.M)
148
+ if len(verdicts) != 1:
149
+ raise ValueError("design review requires one explicit Verifier verdict line")
150
+ return {"collection": "complete", "generationNumber": generation["generation"],
151
+ "generation": dict(binding.generation_ref), "head": generation["head"],
152
+ "base": generation["designReview"]["base"],
153
+ "policyDigest": generation["designReview"]["policyDigest"],
154
+ "censusDigest": canonical_json_digest(generation["designReview"]),
155
+ "invocationRef": invocation.invocation_ref, "attempt": attempt,
156
+ "resultPath": result_path.relative_to(project).as_posix(), "resultDigest": content_digest(raw),
157
+ "expectedCells": len(review.coverage.verdicts) + len(review.coverage.missing),
158
+ "coveredCells": len(review.coverage.verdicts), "missing": dict(review.coverage.missing),
159
+ "unknown": list(review.coverage.unknown), "findings": list(review.findings),
160
+ "blockingFindings": list(review.blocking_findings),
161
+ "verdict": "FAIL" if review.blocking else verdicts[0],
162
+ "scope": "full stage diff; no prior rule judgments inherited"}, body
163
+
164
+
165
+ def _read_attempt_result(
166
+ project: Path, execution: ExecutionManifest, invocation_ref: str, attempt: int,
167
+ ) -> tuple[Path, bytes]:
168
+ row = next((row for row in execution.attempts if (row.invocation_ref, row.attempt)
169
+ == (invocation_ref, attempt)), None)
170
+ if row is None or row.status != "ok" or row.finished_at is None or not row.result_path:
171
+ raise ValueError("design review requires the current completed ok attempt")
172
+ attempt_ref = build_dispatch_id(invocation_ref, attempt)
173
+ seals = [seal for seal in execution.attempt_evidence_seals
174
+ if seal.get("sealRef") == row.evidence_seal_ref and seal.get("attemptRef") == attempt_ref]
175
+ if len(seals) != 1:
176
+ raise ValueError("design review result requires its attempt evidence seal")
177
+ path = Path(row.result_path)
178
+ relative = path.relative_to(project).as_posix() if path.is_absolute() else path.as_posix()
179
+ if not relative.startswith(".okstra/"):
180
+ raise ValueError("design review result must remain in project artifacts")
181
+ path = safe_qa_path(project, relative)
182
+ return path, read_sealed_artifact(AttemptEvidenceSeal.from_payload(seals[0]), path)
183
+
184
+
185
+ def _read_carry(body: str, history: list[dict[str, Any]]) -> list[dict[str, str]]:
186
+ pending = {f"{record['generationNumber']}:{record['invocationRef']}:{record['attempt']}:{identity}"
187
+ for record in history for identity in record.get("blockingFindings", [])}
188
+ if not pending:
189
+ return []
190
+ matches = re.findall(r"^## Design Carry\s*\n```json\s*\n(.*?)\n```", body, re.M | re.S)
191
+ if len(matches) != 1:
192
+ raise ValueError("design review must disposition every earlier blocking finding in Design Carry")
193
+ rows = json.loads(matches[0])
194
+ if not isinstance(rows, list):
195
+ raise ValueError("Design Carry must be an array")
196
+ seen: set[str] = set()
197
+ for row in rows:
198
+ if (not isinstance(row, dict) or set(row) != {"finding", "disposition", "basis"}
199
+ or any(not isinstance(value, str) or not value.strip() for value in row.values())
200
+ or row["finding"] in seen or row["finding"] not in pending
201
+ or row["disposition"] not in ("open", "fixed", "accepted-risk", "rejected")
202
+ or re.search(r"(?:base:)?[A-Za-z0-9_./-]+:[0-9]+", row["basis"]) is None):
203
+ raise ValueError("invalid or duplicate Design Carry disposition")
204
+ seen.add(row["finding"])
205
+ if seen != pending:
206
+ raise ValueError("Design Carry omits earlier blocking findings")
207
+ return rows
208
+
209
+
210
+ def attach_design_reviews(data: dict[str, Any], reviews: Mapping[str, dict[str, Any]]) -> None:
211
+ if not reviews:
212
+ return
213
+ implementation = data.setdefault("implementation", {})
214
+ existing = {row["verifier"]: row for row in implementation.get("verifierResults", [])}
215
+ if existing.keys() - reviews.keys():
216
+ raise ValueError("report verifier is outside the design-review roster")
217
+ rows = []
218
+ for worker, review in reviews.items():
219
+ row = dict(existing.get(worker, {"verifier": worker, "readOnlyCommandLog": "",
220
+ "independentValidationRerun": ""}))
221
+ row.update(verdict=review["verdict"], designReview=review)
222
+ rows.append(row)
223
+ implementation["verifierResults"] = rows
224
+ require_design_acceptance(data, reviews)
225
+
226
+
227
+ def require_design_acceptance(data: Mapping[str, Any], reviews: Mapping[str, Mapping[str, Any]]) -> None:
228
+ token = (data.get("finalVerdict") or {}).get("verdictToken")
229
+ if token not in ("accepted", "conditional-accept"):
230
+ return
231
+ blocked = [worker for worker, row in reviews.items()
232
+ if row["collection"] != "complete" or row["verdict"] in ("FAIL", "not-run")]
233
+ if blocked:
234
+ raise ValueError("design review prevents acceptance: " + ", ".join(blocked))
235
+
236
+
237
+ def validate_design_review_report(
238
+ data: Mapping[str, Any], project: Path, manifest_path: Path, *, head: str = "", base: str = "",
239
+ ) -> None:
240
+ reviews = collect_design_reviews(project, manifest_path)
241
+ if not reviews:
242
+ return
243
+ rows = (data.get("implementation") or {}).get("verifierResults", [])
244
+ reported = {row.get("verifier"): row for row in rows}
245
+ if set(reported) != set(reviews) or len(rows) != len(reviews):
246
+ raise ValueError("report omits or duplicates a design-review verifier")
247
+ for worker, expected in reviews.items():
248
+ if reported[worker].get("designReview") != expected or reported[worker].get("verdict") != expected["verdict"]:
249
+ raise ValueError("report design review differs from sealed verifier result: " + worker)
250
+ if head and expected.get("head") != head:
251
+ raise ValueError("stage head differs from design-review head")
252
+ if base and expected.get("base") != base:
253
+ raise ValueError("stage base differs from design-review base")
254
+ require_design_acceptance(data, reviews)
255
+
256
+
257
+ def validate_stage_design_report(
258
+ project: Path, report: Path, stage: int, *, head: str = "", base: str = "", task_key: str = "",
259
+ ) -> None:
260
+ from .final_report_paths import final_report_data_path
261
+ from .paths import RunRef
262
+
263
+ report = final_report_data_path(report)
264
+ report = safe_qa_path(project, report.absolute().relative_to(project).as_posix())
265
+ manifest_path = RunRef.from_report_path(report).manifest
266
+ manifest = load_owned_object(manifest_path, artifact="implementation run manifest")
267
+ if not design_review_required(project, manifest):
268
+ return
269
+ from .stage_close import _latest_stage_run_manifest
270
+
271
+ if (manifest.get("taskType") != "implementation" or str(manifest.get("stage")) != str(stage)
272
+ or (task_key and manifest.get("taskKey") != task_key)):
273
+ raise ValueError("design-review report belongs to a different task or stage")
274
+ latest = _latest_stage_run_manifest(RunRef.from_report_path(report).task_root, stage)
275
+ if latest != manifest_path:
276
+ raise ValueError("design-review report is not the latest implementation run for this stage")
277
+ data = load_owned_object(report, artifact="implementation report")
278
+ if (data.get("finalVerdict") or {}).get("verdictToken") not in ("accepted", "conditional-accept"):
279
+ raise ValueError("design review has no accepted implementation report")
280
+ validate_design_review_report(data, project, manifest_path, head=head, base=base)
281
+
282
+
283
+ def validate_design_completion(plan_run_root: Path, task_key: str, stage: int, head: str) -> None:
284
+ from .paths import RunRef
285
+ from .stage_close import _latest_stage_run_manifest
286
+
287
+ plan = RunRef.from_run_dir(plan_run_root)
288
+ latest = _latest_stage_run_manifest(plan.task_root, stage)
289
+ if latest is None or plan.project_root is None:
290
+ return
291
+ manifest = load_owned_object(latest, artifact="implementation run manifest")
292
+ if not design_review_required(plan.project_root, manifest):
293
+ return
294
+ if not head:
295
+ raise ValueError("design-review completion requires the stage head")
296
+ report = RunRef.from_manifest(latest, manifest).report
297
+ validate_stage_design_report(plan.project_root, report, stage, head=head, task_key=task_key)
@@ -6,9 +6,14 @@ dispatch 를 정하고 결과를 확정하는 곳은 `team dispatch` / `team awa
6
6
  명령들이 갖고 있다. 리드가 같은 사실을 `okstra lead-progress append` 로 다시
7
7
  적으면 체크포인트마다 전체 컨텍스트를 한 턴씩 쓰는데, 여기서 기록하면 턴이 들지 않는다.
8
8
 
9
- 워커별 체크포인트는 `initial` dispatch 만 센다. reverify·critic·plan-verify 는
10
- 리드가 따로 알리는 이후 라운드이고, 여기서 기록하면 activity-contract run 이
11
- 존재하지 않는 `worker-dispatched` / `worker-completed` 행을 요구받게 된다.
9
+ The per-worker `phase-4-dispatch` line is recorded for `initial` jobs and for the jobs of an
10
+ implementation correction round: its `correction-r<N>` executor and verifier dispatches and
11
+ the reverify rounds that re-converge it (`…-correction-r<N>-reverify-r<k>-…`). The lead
12
+ emits the lines this command prints instead of appending `phase-4-dispatch` itself, so a
13
+ correction round left out here showed the user no dispatch at all. The initial-namespace
14
+ reverify, critic and plan-verify rounds stay out; the lead reports them through
15
+ `phase-5.5-convergence`, `phase-5.6-critic` and `phase-5.5.9-plan-verify`.
16
+ `phase-5-collect` still counts `initial` dispatches only.
12
17
 
13
18
  activity-contract v1 run 에서는 검증기가 워커별 `phase-4-dispatch` /
14
19
  `phase-5-collect` 마다 같은 워커의 `worker-dispatched` / `worker-completed`
@@ -26,8 +31,10 @@ from .agent.activity import (
26
31
  conversation_activity_line,
27
32
  record_activity,
28
33
  )
34
+ from .correction_round import correction_round, invocation_in_correction_namespace
29
35
  from .dispatch_state import (
30
36
  TERMINAL_WORKER_STATUSES,
37
+ WorkerJob,
31
38
  dispatch_worker_key,
32
39
  has_recorded_team_create,
33
40
  worker_dispatch_records,
@@ -35,6 +42,7 @@ from .dispatch_state import (
35
42
  from .json_boundary import JsonBoundaryError, load_owned_object
36
43
  from .lead_progress import record_checkpoint
37
44
  from .worker_prompt_body import REPORT_WRITER_WORKER_ID
45
+ from .worker_prompt_policy import is_reverify_dispatch_kind
38
46
 
39
47
  _INITIAL = "initial"
40
48
 
@@ -63,7 +71,7 @@ def record_dispatch_checkpoints(
63
71
  project_root, run_manifest, "phase-3-team-create", source=source,
64
72
  ))
65
73
  for job in jobs:
66
- if job.dispatch_kind == _INITIAL:
74
+ if _announces_worker_dispatch(job):
67
75
  lines.append(record_checkpoint(
68
76
  project_root, run_manifest, "phase-4-dispatch", source=source,
69
77
  worker=job.worker_id,
@@ -73,7 +81,7 @@ def record_dispatch_checkpoints(
73
81
  lines.append(_record_worker_activity(
74
82
  project_root, run_manifest, source=source,
75
83
  kind="worker-dispatched", agent=job.worker_id,
76
- summary=f"Dispatched {job.worker_id} as an initial worker",
84
+ summary=_dispatch_summary(job),
77
85
  result_path=_project_relative(project_root, str(job.worker_result_path)),
78
86
  outcome="pending",
79
87
  ))
@@ -88,6 +96,21 @@ def record_dispatch_checkpoints(
88
96
  return [line for line in lines if line]
89
97
 
90
98
 
99
+ def _announces_worker_dispatch(job: WorkerJob) -> bool:
100
+ kind = job.dispatch_kind
101
+ if kind == _INITIAL or correction_round(kind) is not None:
102
+ return True
103
+ return is_reverify_dispatch_kind(kind) and invocation_in_correction_namespace(
104
+ job.invocation_id or job.invocation_ref
105
+ )
106
+
107
+
108
+ def _dispatch_summary(job: WorkerJob) -> str:
109
+ if job.dispatch_kind == _INITIAL:
110
+ return f"Dispatched {job.worker_id} as an initial worker"
111
+ return f"Dispatched {job.worker_id} for {job.dispatch_kind}"
112
+
113
+
91
114
  def settled_initial_dispatches(
92
115
  team_state: Mapping[str, Any],
93
116
  ) -> dict[str, Mapping[str, Any]]:
@@ -133,6 +133,7 @@ from .wrapper_status import (
133
133
  log_path_for_prompt,
134
134
  mutation_snapshot_path_for_prompt,
135
135
  prompt_derived_paths,
136
+ read_log_tail,
136
137
  read_wrapper_status,
137
138
  status_path_for_prompt,
138
139
  )
@@ -2015,8 +2016,7 @@ def _wrapper_failure_text(outcome: WorkerOutcome | None) -> str:
2015
2016
  status = read_wrapper_status(outcome.status_sidecar_path)
2016
2017
  if status is None:
2017
2018
  return ""
2018
- failure = _string_value(status.raw.get("failure"))
2019
- return failure[:_MUTATION_REASON_FAILURE_LIMIT]
2019
+ return status.failure[:_MUTATION_REASON_FAILURE_LIMIT]
2020
2020
 
2021
2021
 
2022
2022
  def _mutation_failure_reason(mutation, outcome: WorkerOutcome | None = None) -> str:
@@ -2604,15 +2604,7 @@ def _wrapper_log_tail(job: WorkerJob) -> str | None:
2604
2604
  some process exited 1. Capped well under the writer's own excerpt limit
2605
2605
  because a whole record must stay inside one atomic `PIPE_BUF` append.
2606
2606
  """
2607
- log_path = log_path_for_prompt(job.prompt_path)
2608
- try:
2609
- with log_path.open("rb") as handle:
2610
- handle.seek(0, 2)
2611
- handle.seek(max(0, handle.tell() - _WRAPPER_LOG_TAIL_BYTES))
2612
- tail = handle.read()
2613
- except OSError:
2614
- return None
2615
- return tail.decode("utf-8", errors="replace").strip() or None
2607
+ return read_log_tail(log_path_for_prompt(job.prompt_path), _WRAPPER_LOG_TAIL_BYTES)
2616
2608
 
2617
2609
 
2618
2610
  def _transition_job_status(
@@ -9,7 +9,6 @@ from pathlib import Path
9
9
  from typing import Iterable
10
10
 
11
11
  from okstra_project import ResolverError, project_json_path, resolve_project_root
12
- from okstra_project.resolver import resolve_review_rule_packs
13
12
 
14
13
  from . import worktree_registry
15
14
  from .phases.improvement_discovery import lenses as improvement_lenses
@@ -18,6 +17,7 @@ from .phases.catalog import PhaseAssetError, UnknownTaskType, profile_markdown
18
17
  from .role_requirements import RoleProfileError, load_role_profile
19
18
  from .worktree import is_git_work_tree, main_worktree_path
20
19
  from .json_boundary import JsonBoundaryError, load_owned_object
20
+ from .review_policy import capture_review_policy
21
21
 
22
22
  SUPPORTED_PHASES: tuple[str, ...] = (
23
23
  "implementation",
@@ -182,30 +182,13 @@ def _architecture_declaration_check(project_root: Path) -> DoctorCheck | None:
182
182
 
183
183
 
184
184
  def _review_rule_pack_check(project_root: Path) -> DoctorCheck | None:
185
- """Report a declared review rule pack that no worker will be able to open.
186
-
187
- `reviewRulePacks` is what makes a project's own review standard apply
188
- without every brief citing it, so a stale path costs the whole pack in
189
- silence: the phase records `project-review-rules: declared <path>
190
- unreadable` at best, and a run that reviewed against nothing still passes.
191
- Absent declaration stays quiet — brief-cited packs remain the other, equally
192
- valid, channel.
193
-
194
- What this cannot check is whether a pack that does resolve was actually read
195
- and applied; that stays the worker's own `project-review-rules:` record.
196
- """
197
- declared = resolve_review_rule_packs(project_root)
198
- if not declared:
199
- return None
200
- missing = [path for path in declared if not Path(path).is_file()]
201
- if not missing:
202
- return _ok("review rule packs", f"{len(declared)} declared, all readable")
203
- return _fail(
204
- "review rule packs",
205
- f"declared but not readable: {', '.join(missing)} — phases skip a pack "
206
- "they cannot open, so the run reviews against fewer rules than declared. "
207
- f"Fix the path in {project_json_path(project_root)} or drop the entry.",
208
- )
185
+ try:
186
+ config = load_owned_object(project_json_path(project_root), artifact="project config")
187
+ policy = capture_review_policy(project_root, config)
188
+ except (OSError, ValueError) as exc:
189
+ return _fail("review policy", str(exc))
190
+ return _ok("review policy", f"architecture: {policy['architecture']}; "
191
+ f"{len(policy['sources'])} readable rule sources")
209
192
 
210
193
 
211
194
  def _profile_check(workspace: Path, phase: str) -> DoctorCheck:
@@ -0,0 +1,9 @@
1
+ __all__ = ["capture_record", "ingest_source", "show_record"]
2
+
3
+
4
+ def __getattr__(name: str):
5
+ if name in __all__:
6
+ from . import store
7
+
8
+ return getattr(store, name)
9
+ raise AttributeError(name)
@@ -0,0 +1,91 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ from pathlib import Path
6
+ from typing import get_args
7
+
8
+ from ..fixed_text import line, value_lines
9
+ from ..json_boundary import JsonBoundaryError, external_user_json_source, load_external_json
10
+ from .config import load_config, save_config
11
+ from .contracts import DoyouknowError, MAX_INPUT_BYTES, read_envelope
12
+ from .registration import register_ticket, retry_pending
13
+ from .source_contracts import SourceKind
14
+
15
+
16
+ def _parser() -> argparse.ArgumentParser:
17
+ parser = argparse.ArgumentParser(prog="okstra doyouknow", description="Store linked work records without starting a run.")
18
+ commands = parser.add_subparsers(dest="command", required=True)
19
+ for name in ("capture", "ingest", "show", "sync", "list", "config", "register", "retry"):
20
+ command = commands.add_parser(name)
21
+ if name == "show":
22
+ command.add_argument("record_id")
23
+ elif name in ("capture", "ingest"):
24
+ command.add_argument("--file", required=True, type=Path, help="normalized doyouknow input JSON")
25
+ elif name == "config":
26
+ command.add_argument("--file", type=Path, help="replace source settings from JSON")
27
+ elif name == "register":
28
+ command.add_argument("--ticket", required=True, help="pending registration UUID")
29
+ if name in ("sync", "list", "retry"):
30
+ command.add_argument("--source", choices=get_args(SourceKind))
31
+ if name == "retry":
32
+ command.add_argument("--limit", type=int, default=100)
33
+ if name == "list":
34
+ command.add_argument("--scope")
35
+ command.add_argument("--limit", type=int, default=100)
36
+ command.add_argument("--after", help="source ID returned as nextCursor")
37
+ output = command.add_mutually_exclusive_group()
38
+ output.add_argument("--json", action="store_true", help="emit JSON (default)")
39
+ output.add_argument("--text", action="store_true", help="emit fixed text fields")
40
+ return parser
41
+
42
+
43
+ def _emit(payload: dict, *, text: bool) -> None:
44
+ if not text:
45
+ print(json.dumps(payload, ensure_ascii=False, allow_nan=False))
46
+ return
47
+ rows = ["Okstra doyouknow\n", line("OK", payload["ok"])]
48
+ rows.extend(value_lines("Result", payload))
49
+ print("".join(rows), end="")
50
+
51
+
52
+ def main(argv: list[str] | None = None) -> int:
53
+ args = _parser().parse_args(argv)
54
+ try:
55
+ if args.command == "show":
56
+ from .store import show_record
57
+
58
+ result = show_record(args.record_id)
59
+ elif args.command == "sync":
60
+ from .sync import sync_sources
61
+
62
+ result = sync_sources(source=args.source)
63
+ elif args.command == "register":
64
+ result = register_ticket(args.ticket)
65
+ elif args.command == "retry":
66
+ result = retry_pending(source=args.source, limit=args.limit)
67
+ elif args.command == "list":
68
+ from .source_store import list_sources
69
+
70
+ result = list_sources(scope=args.scope, kind=args.source, limit=args.limit, after=args.after)
71
+ elif args.command == "config":
72
+ settings = load_external_json(external_user_json_source(args.file), artifact="source settings", max_bytes=MAX_INPUT_BYTES) if args.file else None
73
+ result = {"ok": True, "config": save_config(settings) if args.file else load_config()}
74
+ else:
75
+ from .store import capture_record, ingest_source
76
+
77
+ envelope = read_envelope(args.file)
78
+ write = capture_record if args.command == "capture" else ingest_source
79
+ result = write(envelope)
80
+ except ImportError:
81
+ _emit({"ok": False, "reason": "doyouknow storage dependency is unavailable"}, text=args.text)
82
+ return 1
83
+ except (DoyouknowError, JsonBoundaryError, OSError) as exc:
84
+ _emit({"ok": False, "reason": str(exc)}, text=args.text)
85
+ return 1
86
+ _emit(result, text=args.text)
87
+ return 0 if result["ok"] else 1
88
+
89
+
90
+ if __name__ == "__main__":
91
+ raise SystemExit(main())
@@ -0,0 +1,58 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import TypedDict
5
+
6
+ from ..json_boundary import load_owned_object, serialize_owned_object, write_owned_object_atomic
7
+ from ..run_context import dir_flock
8
+ from .contracts import MAX_INPUT_BYTES, asset_object
9
+ from .source_contracts import validate_source_value
10
+ from .paths import database_path, ensure_storage_root, require_database_location as _require_database_location
11
+
12
+
13
+ class SourceConfig(TypedDict):
14
+ schemaVersion: int
15
+ autoRegister: bool
16
+ scope: str | None
17
+ sources: list[str]
18
+ includeProjects: list[str]
19
+ excludeProjects: list[str]
20
+ includeGroups: list[str]
21
+ excludeGroups: list[str]
22
+
23
+
24
+ def load_config(*, home: Path | None = None) -> SourceConfig:
25
+ path = database_path(home).parent / "config.json"
26
+ _require_database_location(path)
27
+ if not path.exists():
28
+ return {"schemaVersion": 1, "autoRegister": True, "scope": None,
29
+ "sources": ["memory", "manager", "task"], "includeProjects": [],
30
+ "excludeProjects": [], "includeGroups": [], "excludeGroups": []}
31
+ payload = load_owned_object(path, artifact="doyouknow config", max_bytes=MAX_INPUT_BYTES)
32
+ validate_source_value(payload)
33
+ serialize_owned_object(path, payload, artifact="doyouknow config", schema=asset_object("doyouknow-config-v1.schema.json"))
34
+ return payload
35
+
36
+
37
+ def save_config(payload: SourceConfig, *, home: Path | None = None) -> SourceConfig:
38
+ validate_source_value(payload)
39
+ path = database_path(home).parent / "config.json"
40
+ _require_database_location(path)
41
+ schema = asset_object("doyouknow-config-v1.schema.json")
42
+ serialize_owned_object(path, payload, artifact="doyouknow config", schema=schema)
43
+ ensure_storage_root(path.parent)
44
+ with dir_flock(path.parent, ".config.lock"):
45
+ write_owned_object_atomic(path, payload, artifact="doyouknow config", schema=schema)
46
+ return payload
47
+
48
+
49
+ def includes_project(settings: SourceConfig, project_id: str) -> bool:
50
+ return _included(project_id, settings["includeProjects"], settings["excludeProjects"])
51
+
52
+
53
+ def includes_group(settings: SourceConfig, group: str) -> bool:
54
+ return _included(group, settings["includeGroups"], settings["excludeGroups"])
55
+
56
+
57
+ def _included(value: str, included: list[str], excluded: list[str]) -> bool:
58
+ return value not in excluded and (not included or value in included)