okstra 0.226.0 → 0.228.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 (103) hide show
  1. package/README.md +2 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/wizard.mjs +12 -15
  5. package/dist/commands/execute/wizard.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +77 -0
  7. package/docs/cli.md +43 -7
  8. package/docs/project-structure-overview.md +13 -3
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/agents/operations/code-review.json +1 -1
  12. package/runtime/prompts/duties/code-reviewer.json +1 -0
  13. package/runtime/prompts/lead/convergence.md +5 -19
  14. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  15. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  16. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  17. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  18. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  19. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  20. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  21. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  22. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  23. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  24. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
  26. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  27. package/runtime/python/okstra_ctl/code_review_target.py +115 -55
  28. package/runtime/python/okstra_ctl/conformance.py +9 -3
  29. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  30. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  31. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  32. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  33. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  34. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  35. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  36. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  37. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  38. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  39. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  40. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  42. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  43. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  44. package/runtime/python/okstra_ctl/paths.py +4 -0
  45. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  46. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  47. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  48. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  49. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  50. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
  53. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  54. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  55. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  60. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  61. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  62. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  63. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  64. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  65. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  66. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  67. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  68. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  69. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  70. package/runtime/python/okstra_ctl/render.py +10 -0
  71. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  72. package/runtime/python/okstra_ctl/run.py +123 -6
  73. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  74. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  75. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  76. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  77. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  78. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  79. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  80. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  81. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  82. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  83. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  84. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  85. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  86. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  87. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  88. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  89. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  90. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  91. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  92. package/runtime/python/okstra_project/dirs.py +22 -0
  93. package/runtime/python/okstra_project/resolver.py +10 -0
  94. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  95. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  96. package/runtime/skills/okstra-code-review/SKILL.md +59 -63
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
  99. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  100. package/runtime/skills/okstra-run/SKILL.md +21 -1
  101. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  102. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  103. package/runtime/validators/validate-brief.py +21 -5
@@ -18,7 +18,8 @@ from __future__ import annotations
18
18
 
19
19
  import re
20
20
  import shlex
21
- from typing import Iterable
21
+ from pathlib import PurePosixPath
22
+ from typing import Iterable, Mapping
22
23
 
23
24
  # 카테고리 화이트리스트. 알 수 없는 카테고리는 오타 가능성이 높으므로 거부.
24
25
  # `db-test` 는 DB/IO/SQL 변경의 실제 DB(또는 충실한 복제) 실행 테스트 전용 카테고리 —
@@ -26,6 +27,11 @@ from typing import Iterable
26
27
  # `test` 와 분리한다. implementation verifier / final-verification 의 DB 실제실행 게이트가
27
28
  # diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
28
29
  ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
30
+ QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
31
+ QA_RELATIVE_PATH_DESCRIPTION = (
32
+ "non-blank relative POSIX path with at least one component after normalization, "
33
+ "without traversal or backslashes"
34
+ )
29
35
 
30
36
  # Mutation 을 유발하거나 lockfile 을 갱신하는 토큰. 각 토큰은 `cmd` 문자열을
31
37
  # 공백으로 단순 분해한 결과 또는 부분 일치 패턴(prefix/suffix sensitive) 로 검출한다.
@@ -185,6 +191,7 @@ def validate_qa_commands(qa: object) -> list[str]:
185
191
  여기서는 raise 하지 않고 메시지를 모아서 호출자가 일괄 보고할 수 있게 한다.
186
192
  """
187
193
  errors: list[str] = []
194
+ seen_ids: set[str] = set()
188
195
  if qa is None:
189
196
  return errors # 옵션 필드 — 미선언은 합법.
190
197
  if not isinstance(qa, dict):
@@ -209,6 +216,10 @@ def validate_qa_commands(qa: object) -> list[str]:
209
216
  continue
210
217
  label = entry.get("label")
211
218
  cmd = entry.get("cmd")
219
+ errors.extend(
220
+ f"qaCommands.{category}[{idx}]: {error}"
221
+ for error in qa_metadata_errors(entry, seen_ids)
222
+ )
212
223
  if not isinstance(label, str) or not label.strip():
213
224
  errors.append(
214
225
  f"qaCommands.{category}[{idx}].label must be a non-empty string"
@@ -228,6 +239,60 @@ def validate_qa_commands(qa: object) -> list[str]:
228
239
  return errors
229
240
 
230
241
 
242
+ def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[str]:
243
+ errors: list[str] = []
244
+ identifier = entry.get("id")
245
+ if identifier is not None:
246
+ if not isinstance(identifier, str) or not re.fullmatch(
247
+ r"[A-Za-z0-9][A-Za-z0-9._-]*", identifier
248
+ ):
249
+ errors.append("qaCommands id must be a safe non-empty identifier")
250
+ elif identifier in seen_ids:
251
+ errors.append(f"duplicate qaCommands id: {identifier}")
252
+ else:
253
+ seen_ids.add(identifier)
254
+ if "procedurePath" in entry:
255
+ if not identifier:
256
+ errors.append("procedurePath requires an id")
257
+ if not qa_relative_path_valid(entry["procedurePath"]):
258
+ errors.append(f"procedurePath must be a {QA_RELATIVE_PATH_DESCRIPTION}")
259
+ for key in ("sourcePaths", "resourceKeys"):
260
+ if key not in entry:
261
+ continue
262
+ values = entry[key]
263
+ if not isinstance(values, list) or any(
264
+ not isinstance(value, str) or not value.strip() for value in values
265
+ ):
266
+ errors.append(f"{key} must be an array of non-empty strings")
267
+ continue
268
+ if len(values) != len(set(values)):
269
+ errors.append(f"{key} must not contain duplicates")
270
+ if key == "sourcePaths" and any(
271
+ not qa_relative_path_valid(value) for value in values
272
+ ):
273
+ errors.append(
274
+ "each sourcePaths item must be a " + QA_RELATIVE_PATH_DESCRIPTION
275
+ )
276
+ if key == "resourceKeys" and any(
277
+ "://" in value or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9:._/-]*", value)
278
+ for value in values
279
+ ):
280
+ errors.append("resourceKeys must be non-secret resource identifiers")
281
+ digest = entry.get("sourceBaselineDigest")
282
+ if digest is not None and (
283
+ not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest)
284
+ ):
285
+ errors.append("sourceBaselineDigest must be a sha256 digest")
286
+ return errors
287
+
288
+
289
+ def qa_relative_path_valid(value: object) -> bool:
290
+ if not isinstance(value, str) or not value.strip() or "\\" in value:
291
+ return False
292
+ path = PurePosixPath(value)
293
+ return bool(path.parts) and not path.is_absolute() and ".." not in path.parts
294
+
295
+
231
296
  def format_errors(errors: Iterable[str]) -> str:
232
297
  """`PrepareError` 등에 그대로 박을 수 있는 멀티라인 문자열."""
233
298
  lines = list(errors)
@@ -0,0 +1,67 @@
1
+ """Typed command inputs and fixed text projections for `okstra qa`."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ from .fixed_text import line
9
+ from .qa_procedures import inspect_commands, register_command
10
+
11
+
12
+ def main(argv: list[str] | None = None) -> int:
13
+ parser = argparse.ArgumentParser(prog="okstra qa")
14
+ parser.add_argument("operation", choices=("register", "show", "check"))
15
+ parser.add_argument("--project-root", type=Path, required=True)
16
+ parser.add_argument("--source-root", type=Path)
17
+ parser.add_argument("--id")
18
+ parser.add_argument("--category", choices=("test", "db-test"))
19
+ parser.add_argument("--label")
20
+ parser.add_argument("--cmd")
21
+ parser.add_argument("--procedure-input", type=Path)
22
+ parser.add_argument("--source-path", action="append", default=[])
23
+ parser.add_argument("--resource-key", action="append", default=[])
24
+ parser.add_argument("--expected-entry-digest")
25
+ args = parser.parse_args(argv)
26
+ source = args.source_root or args.project_root
27
+ try:
28
+ if args.operation == "register":
29
+ required = ("id", "category", "label", "cmd", "procedure_input")
30
+ if any(getattr(args, key) is None for key in required):
31
+ parser.error(
32
+ "register requires --id, --category, --label, --cmd "
33
+ "and --procedure-input"
34
+ )
35
+ entry = {"id": args.id, "label": args.label, "cmd": args.cmd}
36
+ if args.source_path:
37
+ entry["sourcePaths"] = args.source_path
38
+ if args.resource_key:
39
+ entry["resourceKeys"] = args.resource_key
40
+ digest = register_command(
41
+ args.project_root, source, args.category, entry,
42
+ args.procedure_input, expected_digest=args.expected_entry_digest,
43
+ )
44
+ print(line("Registered entry digest", digest), end="")
45
+ return 0
46
+ rows = inspect_commands(args.project_root, source)
47
+ print(line("Source root", str(source.resolve())), end="")
48
+ selection = "explicit" if args.source_root else "original project"
49
+ print(line("Source selection", selection), end="")
50
+ for row in rows:
51
+ print("".join(line(key, row.get(field)) for key, field in (
52
+ ("Category", "category"), ("ID", "id"), ("Label", "label"),
53
+ ("Command", "cmd"), ("Procedure", "procedurePath"),
54
+ ("Entry digest", "entryDigest"), ("Source status", "sourceStatus"),
55
+ ("Execution evidence", "evidenceStatus"))), end="")
56
+ errors = [row["error"] for row in rows if "error" in row]
57
+ if errors:
58
+ raise ValueError("; ".join(errors))
59
+ stale = any(row["sourceStatus"] == "changed" for row in rows)
60
+ return int(args.operation == "check" and stale)
61
+ except (OSError, ValueError) as exc:
62
+ print(f"qa: {exc}", file=sys.stderr)
63
+ return 2
64
+
65
+
66
+ if __name__ == "__main__":
67
+ raise SystemExit(main())
@@ -0,0 +1,235 @@
1
+ """Project verification procedure paths, fingerprints, and atomic registration."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import json
6
+ import os
7
+ import tempfile
8
+ from pathlib import Path
9
+ from typing import Any, Literal, Mapping, TypedDict
10
+
11
+ from okstra_project import project_json_path
12
+ from okstra_project.dirs import OKSTRA_DIR_NAME, json_lock_path, registry_lock
13
+
14
+ from .analysis_packet import _heading_lines
15
+ from .json_boundary import load_owned_object, write_owned_object_atomic
16
+ from .qa_commands import (
17
+ QA_RELATIVE_PATH_DESCRIPTION, qa_relative_path_valid, validate_qa_commands,
18
+ )
19
+
20
+ PROCEDURE_SECTIONS = (
21
+ "Execution", "Environment", "User actions", "Success observations", "Cleanup",
22
+ )
23
+
24
+
25
+ class QaInspectionRow(TypedDict, total=False):
26
+ category: str
27
+ index: int
28
+ id: str
29
+ label: str
30
+ cmd: str
31
+ procedurePath: str
32
+ entryDigest: str
33
+ procedureDigest: str
34
+ sourceStatus: Literal[
35
+ "not-declared", "not-queried", "no-baseline", "unchanged", "changed",
36
+ ]
37
+ evidenceStatus: Literal["not-queried"]
38
+ error: str
39
+
40
+
41
+ def content_digest(value: bytes) -> str:
42
+ return "sha256:" + hashlib.sha256(value).hexdigest()
43
+
44
+
45
+ def canonical_json_digest(value: Mapping[str, Any]) -> str:
46
+ encoded = json.dumps(dict(value), sort_keys=True, separators=(",", ":"))
47
+ return content_digest(encoded.encode())
48
+
49
+
50
+ def safe_qa_path(root: Path, relative: str) -> Path:
51
+ if not qa_relative_path_valid(relative):
52
+ raise ValueError(
53
+ f"QA path must be a {QA_RELATIVE_PATH_DESCRIPTION}: {relative}"
54
+ )
55
+ path = root.resolve()
56
+ for part in Path(relative).parts:
57
+ path = path / part
58
+ if path.is_symlink():
59
+ raise ValueError(f"QA path must not contain a symlink: {relative}")
60
+ return path
61
+
62
+
63
+ def existing_qa_file(root: Path, relative: str) -> Path:
64
+ path = safe_qa_path(root, relative)
65
+ if not path.is_file():
66
+ raise ValueError(f"QA input must be an existing regular file: {relative}")
67
+ return path
68
+
69
+
70
+ def procedure_root(project: Path, source: Path, relative: str) -> Path:
71
+ return project if Path(relative).parts[:1] == (OKSTRA_DIR_NAME,) else source
72
+
73
+
74
+ def validate_procedure_sections(raw: bytes) -> None:
75
+ headings = {text[3:].rstrip("#").strip()
76
+ for _, text in _heading_lines(raw.decode("utf-8").splitlines())
77
+ if text.startswith("## ")}
78
+ missing = set(PROCEDURE_SECTIONS) - headings
79
+ if missing:
80
+ raise ValueError("procedure sections missing: " + ", ".join(sorted(missing)))
81
+
82
+
83
+ def read_validated_procedure(path: Path) -> bytes:
84
+ raw = path.read_bytes()
85
+ validate_procedure_sections(raw)
86
+ return raw
87
+
88
+
89
+ def source_digest(source: Path, relatives: list[str]) -> str:
90
+ return canonical_json_digest({
91
+ relative: content_digest(existing_qa_file(source, relative).read_bytes())
92
+ for relative in sorted(relatives)
93
+ })
94
+
95
+
96
+ def load_qa_config(project: Path) -> dict[str, Any]:
97
+ config = load_owned_object(project_json_path(project), artifact="project config")
98
+ errors = validate_qa_commands(config.get("qaCommands"))
99
+ if errors:
100
+ raise ValueError("; ".join(errors))
101
+ return config
102
+
103
+
104
+ def inspect_commands(project: Path, source: Path) -> list[QaInspectionRow]:
105
+ config = load_qa_config(project)
106
+ rows: list[QaInspectionRow] = []
107
+ for category, entries in (config.get("qaCommands") or {}).items():
108
+ for index, entry in enumerate(entries):
109
+ row: QaInspectionRow = {
110
+ **entry, "category": category, "index": index,
111
+ "entryDigest": canonical_json_digest(entry),
112
+ "sourceStatus": (
113
+ "not-queried" if entry.get("sourcePaths") else "not-declared"
114
+ ),
115
+ "evidenceStatus": "not-queried",
116
+ }
117
+ try:
118
+ relative = entry.get("procedurePath")
119
+ if relative:
120
+ root = procedure_root(project, source, relative)
121
+ raw = read_validated_procedure(existing_qa_file(root, relative))
122
+ row["procedureDigest"] = content_digest(raw)
123
+ if entry.get("sourcePaths"):
124
+ observed = source_digest(source, entry["sourcePaths"])
125
+ baseline = entry.get("sourceBaselineDigest")
126
+ row["sourceStatus"] = "no-baseline" if not baseline else (
127
+ "unchanged" if observed == baseline else "changed"
128
+ )
129
+ except (OSError, ValueError) as exc:
130
+ row["error"] = str(exc)
131
+ rows.append(row)
132
+ return rows
133
+
134
+
135
+ def _store_procedure(project: Path, relative: str, raw: bytes) -> None:
136
+ target = safe_qa_path(project, relative)
137
+ target.parent.mkdir(parents=True, exist_ok=True)
138
+ descriptor, name = tempfile.mkstemp(prefix=".procedure-", dir=target.parent)
139
+ temporary = Path(name)
140
+ try:
141
+ with os.fdopen(descriptor, "wb") as handle:
142
+ handle.write(raw)
143
+ handle.flush()
144
+ os.fsync(handle.fileno())
145
+ try:
146
+ os.link(temporary, target)
147
+ except FileExistsError:
148
+ if existing_qa_file(project, relative).read_bytes() != raw:
149
+ raise ValueError("procedure digest path contains different bytes")
150
+ finally:
151
+ temporary.unlink(missing_ok=True)
152
+
153
+
154
+ def read_registration_input(
155
+ project: Path, source: Path, category: str, entry: Mapping[str, Any],
156
+ procedure: Path,
157
+ ) -> tuple[dict[str, Any], bytes, bool]:
158
+ candidate = dict(entry)
159
+ errors = validate_qa_commands({category: [candidate]})
160
+ if errors or not candidate.get("id"):
161
+ raise ValueError("; ".join(errors) or "registration requires an id")
162
+ absolute = procedure.absolute()
163
+ if ".." in absolute.parts:
164
+ raise ValueError("procedure input must not contain traversal")
165
+ relative = None
166
+ roots = (project.absolute(), project.resolve(), source.absolute(), source.resolve())
167
+ for root in sorted(roots, key=lambda value: len(value.parts), reverse=True):
168
+ if absolute.is_relative_to(root):
169
+ absolute = existing_qa_file(root, absolute.relative_to(root).as_posix())
170
+ break
171
+ selected_roots = (project.resolve(), source.resolve())
172
+ for root in sorted(
173
+ selected_roots, key=lambda value: len(value.parts), reverse=True,
174
+ ):
175
+ if absolute.is_relative_to(root):
176
+ relative = absolute.relative_to(root).as_posix()
177
+ selected = procedure_root(project, source, relative)
178
+ path = existing_qa_file(selected, relative)
179
+ break
180
+ else:
181
+ external_relative = absolute.relative_to(absolute.anchor).as_posix()
182
+ path = existing_qa_file(Path(absolute.anchor), external_relative)
183
+ raw = read_validated_procedure(path)
184
+ external = relative is None
185
+ if external:
186
+ digest = content_digest(raw).split(":", 1)[1]
187
+ relative = (
188
+ f"{OKSTRA_DIR_NAME}/verification/procedures/{candidate['id']}/{digest}.md"
189
+ )
190
+ candidate["procedurePath"] = relative
191
+ if candidate.get("sourcePaths"):
192
+ candidate["sourceBaselineDigest"] = source_digest(
193
+ source, candidate["sourcePaths"]
194
+ )
195
+ return candidate, raw, external
196
+
197
+
198
+ def register_command(
199
+ project: Path, source: Path, category: str, entry: Mapping[str, Any],
200
+ procedure: Path, *, expected_digest: str | None = None,
201
+ ) -> str:
202
+ candidate, raw, external = read_registration_input(
203
+ project, source, category, entry, procedure
204
+ )
205
+ with registry_lock(json_lock_path(project_json_path(project))):
206
+ config = load_qa_config(project)
207
+ qa = config.get("qaCommands") or {}
208
+ config["qaCommands"] = qa
209
+ found = [(key, index, row) for key, rows in qa.items()
210
+ for index, row in enumerate(rows) if row.get("id") == candidate["id"]]
211
+ if found:
212
+ old_category, index, old = found[0]
213
+ if expected_digest != canonical_json_digest(old):
214
+ raise ValueError(
215
+ "existing QA entry digest mismatch; refresh before updating"
216
+ )
217
+ if category != old_category:
218
+ raise ValueError("registration cannot move an id to another category")
219
+ candidate = {**old, **candidate}
220
+ qa[category][index] = candidate
221
+ else:
222
+ if expected_digest is not None:
223
+ raise ValueError(
224
+ "expected QA entry digest supplied but id does not exist"
225
+ )
226
+ qa.setdefault(category, []).append(candidate)
227
+ errors = validate_qa_commands(qa)
228
+ if errors:
229
+ raise ValueError("; ".join(errors))
230
+ if external:
231
+ _store_procedure(project, candidate["procedurePath"], raw)
232
+ write_owned_object_atomic(
233
+ project_json_path(project), config, artifact="project config"
234
+ )
235
+ return canonical_json_digest(candidate)
@@ -0,0 +1,8 @@
1
+ from __future__ import annotations
2
+
3
+ from ..adapters.verification_inputs import JsonVerificationInputStore
4
+ from ..ports.verification_inputs import VerificationInputStore
5
+
6
+
7
+ def default_verification_input_store() -> VerificationInputStore:
8
+ return JsonVerificationInputStore()
@@ -0,0 +1,8 @@
1
+ from __future__ import annotations
2
+
3
+ from ..adapters.worker_defaults import JsonWorkerDefaultsStore
4
+ from ..ports.worker_defaults import WorkerDefaultsStore
5
+
6
+
7
+ def default_worker_defaults_store() -> WorkerDefaultsStore:
8
+ return JsonWorkerDefaultsStore()
@@ -48,6 +48,9 @@ from .ports.worker_dispatch import WorkerDispatchRequest
48
48
  from .registry.host_registry import default_host_registry
49
49
  from .registry.provider_registry import default_provider_registry
50
50
  from .path_hints import compact_active_run_context, hydrate_run_context
51
+ from .verification_input_ref import (
52
+ VerificationInputReference, artifact_fields, retain_recorded_reference,
53
+ )
51
54
  from .paths import task_timeline_file
52
55
  from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
53
56
  from .mcp_servers import load_declarations as load_mcp_declarations
@@ -1709,7 +1712,13 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
1709
1712
  else {}
1710
1713
  )
1711
1714
  except JsonBoundaryError:
1715
+ if VerificationInputReference.from_context(ctx) is not None:
1716
+ raise
1712
1717
  existing_run_manifest = {}
1718
+ manifest_input_ref = retain_recorded_reference(
1719
+ existing_run_manifest if run_manifest_exists else None,
1720
+ VerificationInputReference.from_context(ctx),
1721
+ )
1713
1722
  task_manifest_path = Path(ctx.get("TASK_MANIFEST_PATH", ""))
1714
1723
  task_manifest = {}
1715
1724
  if task_manifest_path.exists():
@@ -1855,6 +1864,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
1855
1864
  "verificationTargetPath": ctx.get("VERIFICATION_TARGET_RELATIVE_PATH", ""),
1856
1865
  "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
1857
1866
  "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
1867
+ **artifact_fields(manifest_input_ref),
1858
1868
  "reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
1859
1869
  "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
1860
1870
  "leadSessionId": ctx.get("CLAUDE_SESSION_ID", ""),
@@ -27,7 +27,10 @@ from .report_synthesis_packet import (
27
27
  )
28
28
  from .conformance import strip_stage_declaration_label
29
29
  from .coverage_census import census_warning_rows, read_census_state
30
- from .design_surfaces import DesignSurfaceError, detect_design_surfaces
30
+ from .design_surfaces import (
31
+ DesignSurfaceError,
32
+ detect_design_surfaces_in_unvalidated_plan,
33
+ )
31
34
  from .design_prep import (
32
35
  DesignPrepError,
33
36
  canonicalize_request_paths,
@@ -251,7 +254,7 @@ def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
251
254
  key: source[key]
252
255
  for key in (
253
256
  "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
254
- "origin", "userConfirmation", "userInput", "options",
257
+ "origin", "userConfirmation", "userInput", "options", "candidateRef",
255
258
  )
256
259
  if key in source
257
260
  }
@@ -440,7 +443,7 @@ def _clarification_row(
440
443
  key: source[key]
441
444
  for key in (
442
445
  "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
443
- "origin", "userConfirmation", "options",
446
+ "origin", "userConfirmation", "options", "candidateRef",
444
447
  )
445
448
  if key in source
446
449
  }
@@ -697,18 +700,15 @@ def validate_plan_draft(
697
700
 
698
701
 
699
702
  def _design_surface_errors(draft: Mapping[str, Any]) -> list[str]:
700
- """`plan-items prepare` 가 돌릴 설계 표면 탐지기를 초안 단계에서 미리 돌린다.
703
+ """Run the design-surface detector that `plan-items prepare` runs, on the draft.
701
704
 
702
- 탐지 실패는 서사를 고쳐야 풀리는데, 교정 원장 대조가 이를 몰라 ok 를 낸 뒤
703
- prepare 에서야 드러났다.
705
+ Only a narrative edit resolves a detection failure, so it must surface in the
706
+ draft check, where the writer can still correct it in the same run.
704
707
  """
705
- planning = draft.get("implementationPlanning")
706
- if not isinstance(planning, Mapping) or not planning.get("stages"):
707
- return []
708
708
  try:
709
- detect_design_surfaces(planning)
710
- except (DesignSurfaceError, TypeError, AttributeError) as exc:
711
- return [f"implementationPlanning: design-surface detection failed: {exc}"]
709
+ detect_design_surfaces_in_unvalidated_plan(draft.get("implementationPlanning"))
710
+ except DesignSurfaceError as exc:
711
+ return [f"implementationPlanning: {exc}"]
712
712
  return []
713
713
 
714
714