okstra 0.227.0 → 0.228.1

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 (76) hide show
  1. package/README.md +1 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/docs/architecture/storage-model.md +77 -0
  5. package/docs/cli.md +15 -3
  6. package/docs/project-structure-overview.md +12 -2
  7. package/package.json +1 -1
  8. package/runtime/BUILD.json +2 -2
  9. package/runtime/prompts/coding-preflight/clean-code.md +24 -18
  10. package/runtime/prompts/coding-preflight/overview.md +6 -6
  11. package/runtime/prompts/duties/code-reviewer.json +1 -0
  12. package/runtime/prompts/lead/convergence.md +5 -19
  13. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  14. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  15. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  16. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
  17. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  18. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  19. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  20. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  21. package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
  22. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  23. package/runtime/python/okstra_ctl/code_review_target.py +46 -10
  24. package/runtime/python/okstra_ctl/conformance.py +9 -3
  25. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  26. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  27. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  28. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  29. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  30. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  31. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  32. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  33. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  34. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  35. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  36. package/runtime/python/okstra_ctl/paths.py +4 -0
  37. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  38. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  39. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  40. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  41. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
  42. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
  43. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  44. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  45. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  47. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  48. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  49. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  50. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  51. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  52. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  53. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  54. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  55. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  56. package/runtime/python/okstra_ctl/render.py +10 -0
  57. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  58. package/runtime/python/okstra_ctl/run.py +108 -5
  59. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  60. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  61. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  62. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  63. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  64. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  65. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  66. package/runtime/python/okstra_project/dirs.py +22 -0
  67. package/runtime/python/okstra_project/resolver.py +10 -0
  68. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  69. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  70. package/runtime/skills/okstra-code-review/SKILL.md +39 -45
  71. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  72. package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
  73. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  74. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  75. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  76. package/runtime/validators/validate-brief.py +21 -5
@@ -102,7 +102,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
102
102
  | `okstra lead-progress append --project-root <dir> --run-manifest <path> --phase <phase-id>` | Every `PROGRESS` checkpoint the command performing that step does not record itself; print the `progressLine` it returns. `--phase` accepts only the listed phase ids; use `--worker`, `--field NAME=VALUE`, and `--detail <text>` for the rest | this contract "Progress reporting" |
103
103
  | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <agent> --outcome <outcome> --summary <text>` | Before each activity boundary when the run manifest declares `activityContractVersion: 1`, except a `worker-dispatched` / `worker-completed` row the dispatching command already appended (see "Progress reporting") | launch prompt "Progress reporting" |
104
104
  | `okstra error-log append-observed --out <errors-path> --task-key <key> --phase <phase> --agent <provider-worker> --agent-role <role> --model <model> --error-type <type> --command-kind <kind> --command <command> --message <text>` | Record an observed failure. `--agent` takes the provider worker id (`codex-worker`); an execution label goes in `--execution-label` | this contract "Errors log path wiring"; `team-contract` "Worker error-log command" |
105
- | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>]` | Open an approval blocker after the user confirmed it | this contract "User confirmation before an approval blocker" |
105
+ | `okstra approval-decision open --ledger <path> --task-key <key> --task-type <type> --run-seq <seq> --clarification-id <C-NNN> --ticket-id <id> --statement <text> --expected-form <form> --classification <class> --origin <origin> --user-confirmation <text> --unblock-condition <text> --recommended-disposition <disposition> [--supersedes <C-NNN>] [--candidate-ref <IO-NNN>]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts | this contract "User confirmation before an approval blocker" |
106
106
  | `okstra approval-decision carry --ledger <path> --clarification-id <C-NNN> --from-responses <path>` | Carry a decision answered in an earlier run | `report-writer` "Role-owned inputs" |
107
107
  | `okstra approval-decision resolve --ledger <path> --clarification-id <C-NNN> --disposition <disposition> --user-text <text> --user-response-ref <ref>` | Record the user's disposition of an approval row; it touches no verdict | `plan-body-verification` "Round protocol" |
108
108
  | `okstra user-response show --report <path>` | Not a lead step: the `okstra-user-response` skill reads approval rows through it, so an `origin` outside the schema enum breaks every later read | `plan-body-verification` "Round protocol" |
@@ -16,7 +16,7 @@ prompt through `prepare_agent_invocation()` before `worker-dispatch`.
16
16
  Load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
17
17
 
18
18
  - **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework from its extension or project manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`), then read that pack's resources via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
19
- - **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Consume its `Architecture style`, `Project Review Rule Packs`, and `Project QA Commands` sections; do not open Okstra-owned JSON storage.
19
+ - **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Consume its `Architecture style` and `Project Review Rule Packs` sections. Follow the `**Verification inputs:**` declaration-source rule when that header is present; use the named `okstra model-io verification-input --run-manifest <run-manifest>` projection for frozen declarations. The legacy lookup uses the projection's `Project QA Commands` only for an unfrozen baseline. Consume fixed text projections; do not open Okstra-owned JSON storage.
20
20
  - **Declared architecture style — an authoritative Stage 3 input, and it binds.** A projected `hexagonal` selects `architectures/hexagonal.md` even when none of Stage 3's layout signals matched, so the declaration — not the directory shape — decides. A projected `layered` has no pack resource; its invariant applies from this line: dependencies run one direction only — an upper layer may import a lower one, never the reverse — and a variation point is extracted onto a layer boundary. A declared style makes this overlay binding rather than advisory, and which rule binds follows the style: under `hexagonal` the overlay's otherwise-advisory concrete-adapter item is blocking, so a service dependency you add or modify goes through a port instead of a concrete implementation and that placement violation is fixed before the write rather than recorded as a note; under `layered` what binds is the direction invariant just stated — your own judgement over the import list of every file the diff touches, plus extracting a variation point onto a layer boundary — while the concrete-adapter item stays advisory, since `layered` has no ports to route it through. An absent or `none` projected style leaves Stage 3 detection-driven and its overlay advisory. The verifier re-grades the same diff under the same declaration (`_implementation-verifier.md` → Static design & test-quality review), so a placement violation missed here returns as a verdict `FAIL`.
21
21
  - **Project review rule packs:** a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or the project-context projection lists it as a standing standard. The two sources are a union. Read only those files and the `references/*.md` files they directly name; a declared path that will not open is recorded as `project-review-rules: declared <path> unreadable`, never silently dropped. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
22
22
  - **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
@@ -0,0 +1,22 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+
5
+ from ..paths import RunRef
6
+ from ..verification_input_ref import VerificationInputReference
7
+ from ..verification_input_types import VerificationInputs
8
+ from ..verification_inputs import prepare_verification_inputs, read_verification_inputs
9
+
10
+
11
+ class JsonVerificationInputStore:
12
+ def freeze(
13
+ self, project: Path, source: Path, ref: RunRef,
14
+ *, approved_plan: Path | None,
15
+ ) -> VerificationInputReference:
16
+ path, digest = prepare_verification_inputs(
17
+ project, source, ref, approved_plan=approved_plan,
18
+ )
19
+ return VerificationInputReference(path.relative_to(project).as_posix(), digest)
20
+
21
+ def read(self, path: Path, digest: str) -> VerificationInputs:
22
+ return read_verification_inputs(path, digest)
@@ -4,7 +4,7 @@ from collections.abc import Mapping
4
4
  from pathlib import Path
5
5
 
6
6
  from okstra_project import project_json_path
7
- from okstra_project.dirs import okstra_home
7
+ from okstra_project.dirs import json_lock_path, okstra_home
8
8
 
9
9
  from ..domain.worker_defaults import (
10
10
  WorkerDefaultError,
@@ -55,7 +55,7 @@ class JsonWorkerDefaultsStore:
55
55
  before: Mapping[str, object],
56
56
  ) -> dict[str, object]:
57
57
  path = self.scope_path(scope, project_root)
58
- with registry_lock(path.with_suffix(path.suffix + ".lock")):
58
+ with registry_lock(json_lock_path(path)):
59
59
  config, current = _read_worker_config(path)
60
60
  values = merge_worker_default_updates(current, before, updates)
61
61
  config["workerDefaults"] = values
@@ -181,8 +181,7 @@ def build_analysis_packet(
181
181
  )
182
182
  )
183
183
  # The directive overrides the brief and the plan text below it, so it comes
184
- # before them. As the last section of a 4,865-line packet (dev-11562), an
185
- # executor stopped on a plan/brief conflict the directive had resolved.
184
+ # before them: a reader that stops early must already have seen it.
186
185
  parts.extend(_directive_block(directive))
187
186
  # 짧은 포인터 절이라 46KB 에서 잘리는 읽기에서도 도착하도록 브리프보다 앞에 둔다.
188
187
  if technical_evidence_text:
@@ -227,6 +226,9 @@ def build_analysis_packet(
227
226
 
228
227
  _HEADING_RE = re.compile(r"\A#{1,2} \S")
229
228
  _FENCE_RE = re.compile(r"\A\s*(?P<marker>`{3,}|~{3,})(?P<info>.*)\Z")
229
+ # One page size for every packet read instruction: the section index, the worker
230
+ # prompt's read-scope header and the worker preamble must not disagree.
231
+ PACKET_PAGE_LINES = 200
230
232
  # 목차 자신이 차지하는 줄 수 중 표제 행을 뺀 나머지. 행 수는 표제 개수로
231
233
  # 정해지므로 삽입 전에 전체 이동량을 계산할 수 있다.
232
234
  _INDEX_PREAMBLE_LINES = 5
@@ -317,7 +319,8 @@ def _with_section_index(body: str) -> str:
317
319
  " `sed -n '<start>,<end>p'` rather than opening the whole file: a"
318
320
  " whole-file read is truncated by some worker CLIs without reporting"
319
321
  " it, and the sections that describe current state are last. Page a"
320
- " range longer than 200 lines in 200-line reads.",
322
+ f" range longer than {PACKET_PAGE_LINES} lines"
323
+ f" in {PACKET_PAGE_LINES}-line reads.",
321
324
  "",
322
325
  *rows,
323
326
  ]
@@ -516,35 +519,35 @@ def _group_memory_block(
516
519
  return lines
517
520
 
518
521
 
519
-
520
522
  def cited_documents_block(brief_text: str, project_root: Path) -> str:
521
523
  """브리프 Source Material 이 참조로 인용한 로컬 파일을 패킷 절로 싣는다.
522
524
 
523
525
  `- format: by-reference` 인 `### Source N — file` 항목은 본문 대신 파일을
524
- 가리킨다. task worktree 는 체크아웃이라 프로젝트 루트의 untracked 파일
525
- (`.project-docs/` 스펙)이 없고, 설계자들은 그 스펙이 이미 정한 점에
526
- `uncertain` 을 던졌다(fontradar dev-11562). prepare 는 Source Material 이
527
- 인용한 경로만 프로젝트 루트에서 읽기 전용으로 읽고, 루트 밖 경로는 읽지
528
- 않는다(artifact-home 규칙).
526
+ 가리킨다. The task worktree is a checkout, so it lacks untracked files in
527
+ the project root (such as `.project-docs/` specs); prepare reads only the
528
+ cited paths, read-only, from the project root, and never a path outside it
529
+ (artifact-home rule).
529
530
  """
530
531
  root = project_root.resolve()
531
532
  entries: list[str] = []
532
533
  for ref in _by_reference_file_refs(_section_map(brief_text).get("Source Material", "")):
533
- candidate = Path(ref).expanduser()
534
- path = (candidate if candidate.is_absolute() else root / candidate).resolve()
535
- try:
536
- relative = path.relative_to(root).as_posix()
537
- except ValueError:
538
- entries.append(f"### `{ref}`\n\n- not read: outside the project root")
534
+ relative = project_relative_ref(ref, root)
535
+ if relative is None:
536
+ entries.append(
537
+ f"### `{ref}`\n\n"
538
+ "- not read: does not resolve to a path under the project root"
539
+ )
539
540
  continue
541
+ path = root / relative
540
542
  if not path.is_file():
541
543
  entries.append(f"### `{relative}`\n\n- not read: no such file under the project root")
542
544
  continue
543
- content = path.read_bytes()
544
- if len(content) > MAX_CITED_DOCUMENT_BYTES:
545
+ with path.open("rb") as handle:
546
+ content = handle.read(MAX_CITED_DOCUMENT_BYTES + 1)
547
+ if exceeds_cited_document_limit(len(content)):
545
548
  entries.append(
546
- f"### `{relative}`\n\n- not read: {len(content)} bytes exceeds "
547
- f"{MAX_CITED_DOCUMENT_BYTES}; paste the cited part into Source Material"
549
+ f"### `{relative}`\n\n- not read: exceeds {MAX_CITED_DOCUMENT_BYTES} "
550
+ "bytes; paste the cited part into Source Material"
548
551
  )
549
552
  continue
550
553
  text = content.decode("utf-8", errors="replace").rstrip("\n")
@@ -567,6 +570,30 @@ def cited_documents_block(brief_text: str, project_root: Path) -> str:
567
570
  ])
568
571
 
569
572
 
573
+ def exceeds_cited_document_limit(size: int) -> bool:
574
+ """Whether prepare refuses to copy a cited file of `size` bytes into the packet."""
575
+ return size > MAX_CITED_DOCUMENT_BYTES
576
+
577
+
578
+ def project_relative_ref(ref: str, root: Path) -> str | None:
579
+ """The posix path of a Source Material `ref` relative to the resolved `root`.
580
+
581
+ None when the ref resolves outside the root, or names the home directory of
582
+ a user this machine does not know (`~200` in prose). Every reader and
583
+ writer of a `### Source N — file` ref goes through here so they agree on
584
+ which file it names.
585
+ """
586
+ try:
587
+ candidate = Path(ref).expanduser()
588
+ except RuntimeError:
589
+ return None
590
+ path = (candidate if candidate.is_absolute() else root / candidate).resolve()
591
+ try:
592
+ return path.relative_to(root).as_posix()
593
+ except ValueError:
594
+ return None
595
+
596
+
570
597
  def _by_reference_file_refs(source_material: str) -> list[str]:
571
598
  refs = [ref for ref, fmt in file_source_entries(source_material) if fmt == BY_REFERENCE_FORMAT]
572
599
  return list(dict.fromkeys(refs))
@@ -591,10 +618,14 @@ def file_source_entries(source_material: str) -> list[tuple[str, str]]:
591
618
  match.groups() for line in block[1:]
592
619
  if (match := _SOURCE_FIELD_RE.match(line))
593
620
  )
594
- if fields.get("ref", "").strip():
595
- entries.append((fields["ref"].strip(), fields.get("format", "").strip()))
621
+ # A ref written as inline code (`` `docs/spec.md` ``) names the path
622
+ # inside the backticks.
623
+ ref = fields.get("ref", "").strip().strip("`").strip()
624
+ if ref:
625
+ entries.append((ref, fields.get("format", "").strip()))
596
626
  return entries
597
627
 
628
+
598
629
  def _brief_block(brief_text: str) -> list[str]:
599
630
  return [
600
631
  "",
@@ -39,6 +39,17 @@ def _schema_enum(definition: str) -> frozenset[str]:
39
39
  return frozenset(str(value) for value in values)
40
40
 
41
41
 
42
+ @lru_cache(maxsize=None)
43
+ def _schema_pattern(definition: str) -> str:
44
+ schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
45
+ pattern = (schema.get("$defs") or {}).get(definition, {}).get("pattern")
46
+ if not isinstance(pattern, str) or not pattern:
47
+ raise ApprovalDecisionError(
48
+ f"report schema has no pattern for {definition!r}"
49
+ )
50
+ return pattern
51
+
52
+
42
53
  DISPOSITIONS = frozenset({"select", "accept-risk", "request-revision", "reject"})
43
54
  REACHES = frozenset({"in-repo", "cross-repo"})
44
55
  SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
@@ -223,6 +234,7 @@ def open_decision(
223
234
  classification: str, origin: str, user_confirmation: str,
224
235
  unblock_condition: str, recommended_disposition: str,
225
236
  options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
237
+ candidate_ref: str = "",
226
238
  ) -> None:
227
239
  row = _decision_row(
228
240
  clarification_id=clarification_id, ticket_id=ticket_id,
@@ -239,10 +251,19 @@ def open_decision(
239
251
  raise ApprovalDecisionError(f"duplicate active clarification: {clarification_id}")
240
252
  if supersedes:
241
253
  row["supersedes"] = _superseded_carried_ids(ledger, supersedes)
254
+ if candidate_ref:
255
+ row["candidateRef"] = _candidate_ref(candidate_ref)
242
256
  active.append(row)
243
257
  write_json_atomic(ledger_path, ledger)
244
258
 
245
259
 
260
+ def _candidate_ref(value: str) -> str:
261
+ ref = value.strip()
262
+ if re.search(_schema_pattern("ImplementationOptionId"), ref) is None:
263
+ raise ApprovalDecisionError(f"candidate_ref must be an option id (IO-NNN): {value!r}")
264
+ return ref
265
+
266
+
246
267
  def _superseded_carried_ids(
247
268
  ledger: Mapping[str, Any], supersedes: Sequence[str],
248
269
  ) -> list[str]:
@@ -442,6 +463,14 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
442
463
  "Repeat for several ids."
443
464
  ),
444
465
  )
466
+ parser.add_argument(
467
+ "--candidate-ref",
468
+ default="",
469
+ help=(
470
+ "the implementation option (IO-NNN) this decision is about. A "
471
+ "candidate's splitAcceptance may cite only a decision opened for it."
472
+ ),
473
+ )
445
474
 
446
475
 
447
476
  _CLI_EPILOG = r"""Usage:
@@ -523,7 +552,7 @@ def _open_from_args(args: argparse.Namespace) -> None:
523
552
  # 행이고, 이월 행은 `answered` 로 실린다.
524
553
  _QUESTION_FIELDS = (
525
554
  "id", "ticketId", "kind", "statement", "expectedForm", "blocks", "origin",
526
- "options",
555
+ "options", "candidateRef",
527
556
  )
528
557
 
529
558
 
@@ -1,17 +1,18 @@
1
1
  """Project an approved implementation-planning report onto one stage.
2
2
 
3
- An implementation executor owns exactly one stage, but its prompt pointed it at
4
- the whole plan record. Measured 2026-10-30 (fontradar-v2-api dev-11562 stage 1):
5
- that record was 7,465 lines / 385 KB, 94 KB of it the planning phase's own
6
- verification ledger, and a codex executor reported `contract-violated` because
7
- its reads overran the CLI's tool-output limit before it made an edit.
3
+ An implementation executor owns exactly one stage, while the whole plan record
4
+ also carries every other stage, the planning phase's verification ledger and the
5
+ approver's presentation. Reading that record end-to-end can overrun a CLI's
6
+ tool-output limit before the executor makes an edit.
8
7
 
9
8
  The extract keeps everything the stage can act on and drops only what is named
10
9
  in `OMITTED`, each with the reason, so a reader can tell an omission from a gap.
11
- Rows of a row family keep the stage's rows plus every row that names no stage
12
- (`plan_items._stage_scope` reads that as "applies to every stage"), and every
13
- row carries the `P-*` id the plan-body verification and lead directives cite it
14
- by. The full record stays the source of record behind `sourcePlanPath`.
10
+ Requirement-coverage and validation rows, the two families whose rows carry
11
+ `stageRefs`, keep the stage's rows plus every row that names no stage
12
+ (`plan_items.stage_scope` reads that as "applies to every stage"). Every row of
13
+ a plan-item family carries the `P-*` id the plan-body verification and lead
14
+ directives cite it by. The full record stays the source of record behind
15
+ `sourcePlanPath`.
15
16
  """
16
17
  from __future__ import annotations
17
18
 
@@ -20,26 +21,22 @@ import re
20
21
  from pathlib import Path
21
22
  from typing import Any, Mapping
22
23
 
24
+ from .design_surfaces import PATH_CHARS, stages_touching_declared_path
23
25
  from .json_boundary import load_owned_object, write_owned_object_atomic
24
- from .plan_items import PLAN_ITEM_SOURCES
26
+ from .plan_items import PLAN_ITEM_SOURCES, stage_scope
25
27
 
26
28
  EXTRACT_KIND = "approved-plan-stage-extract"
27
29
  EXTRACT_SCHEMA_VERSION = 1
28
30
 
29
- # implementationPlanning row families filtered to the stage. Every other
30
- # implementationPlanning key is carried whole unless OMITTED names it.
31
- _STAGE_ROW_FAMILIES = (
32
- "requirementCoverage",
33
- "validationChecklist",
34
- "rollbackStrategy",
35
- "dependencyMigrationRisk",
36
- "crossProjectDependencies",
37
- )
31
+ # implementationPlanning row families filtered to the stage: the report schema
32
+ # gives `stageRefs` to these rows only. Every other implementationPlanning key
33
+ # is carried whole unless OMITTED names it.
34
+ _STAGE_ROW_FAMILIES = ("requirementCoverage", "validationChecklist")
38
35
  # plan_items numbers a row family by position (`P-Val-4` is the fourth
39
36
  # validation row); a filtered list loses the position, so the id travels on the row.
40
37
  _PLAN_ITEM_PREFIX = {
41
38
  family: prefix for family, prefix, _ in PLAN_ITEM_SOURCES
42
- if family in _STAGE_ROW_FAMILIES
39
+ if family in (*_STAGE_ROW_FAMILIES, "rollbackStrategy", "dependencyMigrationRisk")
43
40
  }
44
41
  # Top-level report keys an executor acts on. Everything else at the top level is
45
42
  # report presentation, audit, or accounting and is listed in OMITTED.
@@ -59,20 +56,30 @@ OMITTED = {
59
56
  "the stage-scoped effective decision is inlined in the executor prompt "
60
57
  "under Effective design preparation"
61
58
  ),
62
- "implementationPlanning.userNarrative": "plain-language explanation for the human reader",
63
- "implementationPlanning.stages[other]": "stages this run does not own; their Stage Map rows stay",
59
+ "implementationPlanning.userNarrative": (
60
+ "plain-language explanation for the human reader"
61
+ ),
62
+ "implementationPlanning.stages[other]": (
63
+ "stages this run does not own; their Stage Map rows stay"
64
+ ),
64
65
  "implementationPlanning.directionRealization.fileStructure[other]": (
65
- "file rows whose path this stage's entry never names"
66
+ "file rows whose path or id this stage's entry never names and that the "
67
+ "planning gate's path mapping assigns to no step of this stage"
66
68
  ),
67
69
  "<rows of another stage>": (
68
- "requirementCoverage / validationChecklist / rollbackStrategy / "
69
- "dependencyMigrationRisk / crossProjectDependencies rows whose stageRefs "
70
- "exclude this stage and whose id this stage's entry never cites"
70
+ "requirementCoverage / validationChecklist rows whose stageRefs exclude "
71
+ "this stage and whose id this stage's entry never cites"
71
72
  ),
72
- "humanSummary, verdictCard, rationale, summary, finalVerdict, recommendedNextSteps": (
73
+ (
74
+ "humanSummary, verdictCard, rationale, summary, finalVerdict, "
75
+ "recommendedNextSteps"
76
+ ): (
73
77
  "report presentation for the approver"
74
78
  ),
75
- "crossVerification, agentActivity, evidence, executionStatus, executionRoles, tokenUsage": (
79
+ (
80
+ "crossVerification, agentActivity, evidence, executionStatus, "
81
+ "executionRoles, tokenUsage"
82
+ ): (
76
83
  "planning-run audit and accounting"
77
84
  ),
78
85
  "meta, frontmatter, header": "report identity",
@@ -101,8 +108,12 @@ def stage_extract_payload(
101
108
  carried_planning[key] = [stage_entry]
102
109
  elif key in _STAGE_ROW_FAMILIES:
103
110
  carried_planning[key] = _stage_rows(value, key, stage_number, cited_text)
111
+ elif key in _PLAN_ITEM_PREFIX:
112
+ carried_planning[key] = _numbered_rows(value, key)
104
113
  elif key == "directionRealization" and isinstance(value, Mapping):
105
- carried_planning[key] = _direction_realization(value, cited_text)
114
+ carried_planning[key] = _direction_realization(
115
+ value, stage_number, stage_entry, cited_text
116
+ )
106
117
  else:
107
118
  carried_planning[key] = value
108
119
  payload: dict[str, Any] = {
@@ -123,24 +134,23 @@ def stage_extract_payload(
123
134
  return payload
124
135
 
125
136
 
126
- def materialize_stage_extract(
127
- plan_path: Path,
128
- stage_number: int,
129
- output_path: Path,
130
- ) -> bool:
131
- """Write the extract for a `.data.json` plan; False when the plan is not one.
137
+ def load_stage_extract(plan_path: Path, stage_number: int) -> dict[str, Any] | None:
138
+ """The extract of a `.data.json` plan; None when the plan is not one.
132
139
 
133
140
  A Markdown plan predates the report record and has no structure to project,
134
141
  and a missing file is reported by the prompt's own plan anchor, so neither
135
142
  is an error here — the executor reads the plan as it did before.
136
143
  """
137
144
  if not plan_path.name.endswith(".data.json") or not plan_path.is_file():
138
- return False
145
+ return None
139
146
  report = load_owned_object(plan_path, artifact="approved implementation plan")
140
- payload = stage_extract_payload(report, stage_number, str(plan_path))
141
- output_path.parent.mkdir(parents=True, exist_ok=True)
142
- write_owned_object_atomic(output_path, payload, artifact="approved plan stage extract")
143
- return True
147
+ return stage_extract_payload(report, stage_number, str(plan_path))
148
+
149
+
150
+ def write_stage_extract(output_path: Path, payload: Mapping[str, Any]) -> None:
151
+ write_owned_object_atomic(
152
+ output_path, payload, artifact="approved plan stage extract"
153
+ )
144
154
 
145
155
 
146
156
  def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str, Any]:
@@ -153,42 +163,41 @@ def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str,
153
163
  raise StageExtractError(f"approved plan has no stage {stage_number}")
154
164
 
155
165
 
156
- def _stage_rows(
157
- rows: Any,
158
- family: str,
159
- stage_number: int,
160
- cited_text: str,
161
- ) -> list[Any]:
166
+ def _numbered_rows(rows: Any, family: str) -> Any:
162
167
  if not isinstance(rows, list):
163
168
  return rows
164
- kept = []
165
- for position, row in enumerate(rows, start=1):
166
- if not isinstance(row, Mapping):
167
- kept.append(row)
168
- continue
169
- if not _row_applies(row, stage_number, cited_text):
170
- continue
171
- prefix = _PLAN_ITEM_PREFIX.get(family)
172
- kept.append(
173
- {"planItemId": f"{prefix}-{position}", **row} if prefix else dict(row)
174
- )
175
- return kept
169
+ prefix = _PLAN_ITEM_PREFIX[family]
170
+ return [
171
+ {"planItemId": f"{prefix}-{position}", **row}
172
+ if isinstance(row, Mapping)
173
+ else row
174
+ for position, row in enumerate(rows, start=1)
175
+ ]
176
+
177
+
178
+ def _stage_rows(rows: Any, family: str, stage_number: int, cited_text: str) -> Any:
179
+ numbered = _numbered_rows(rows, family)
180
+ if not isinstance(numbered, list):
181
+ return numbered
182
+ return [
183
+ row for row in numbered
184
+ if not isinstance(row, Mapping) or _row_applies(row, stage_number, cited_text)
185
+ ]
176
186
 
177
187
 
178
188
  def _row_applies(row: Mapping[str, Any], stage_number: int, cited_text: str) -> bool:
179
- refs = row.get("stageRefs")
180
- stages = (
181
- [value for value in refs if isinstance(value, int) and not isinstance(value, bool)]
182
- if isinstance(refs, list) else []
183
- )
184
- if not stages or stage_number in stages:
189
+ scope = stage_scope(row)
190
+ if scope is None or stage_number in scope:
185
191
  return True
186
192
  row_id = row.get("id")
187
193
  return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
188
194
 
189
195
 
190
196
  def _direction_realization(
191
- realization: Mapping[str, Any], cited_text: str
197
+ realization: Mapping[str, Any],
198
+ stage_number: int,
199
+ stage_entry: Mapping[str, Any],
200
+ cited_text: str,
192
201
  ) -> dict[str, Any]:
193
202
  carried = dict(realization)
194
203
  rows = realization.get("fileStructure")
@@ -197,10 +206,35 @@ def _direction_realization(
197
206
  row for row in rows
198
207
  if not isinstance(row, Mapping)
199
208
  or not isinstance(row.get("path"), str)
200
- or row["path"] in cited_text
209
+ or _file_row_applies(row, stage_number, stage_entry, cited_text)
201
210
  ]
202
211
  return carried
203
212
 
204
213
 
214
+ def _file_row_applies(
215
+ row: Mapping[str, Any],
216
+ stage_number: int,
217
+ stage_entry: Mapping[str, Any],
218
+ cited_text: str,
219
+ ) -> bool:
220
+ path = row["path"]
221
+ if _names_path(cited_text, path):
222
+ return True
223
+ if stage_number in stages_touching_declared_path(path, {stage_number: stage_entry}):
224
+ return True
225
+ row_id = row.get("id")
226
+ return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
227
+
228
+
229
+ def _names_path(text: str, path: str) -> bool:
230
+ # The stage entry is prose in the report language, unlike the gate's path
231
+ # cells: a path may carry a `./` prefix, end a sentence or touch a non-ASCII
232
+ # particle, but must not sit inside a longer path.
233
+ pattern = (
234
+ rf"(?<![{PATH_CHARS}])(?:\./)?{re.escape(path)}(?=\.?(?![{PATH_CHARS}]))"
235
+ )
236
+ return re.search(pattern, text, flags=re.ASCII) is not None
237
+
238
+
205
239
  def _cites(text: str, identifier: str) -> bool:
206
240
  return re.search(rf"(?<![\w-]){re.escape(identifier)}(?![\w-])", text) is not None