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.
- package/README.md +1 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/coding-preflight/clean-code.md +24 -18
- package/runtime/prompts/coding-preflight/overview.md +6 -6
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- 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
|
|
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(
|
|
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
|
|
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
|
|
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
|
|
525
|
-
(`.project-docs/`
|
|
526
|
-
|
|
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
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
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
|
-
|
|
544
|
-
|
|
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: {
|
|
547
|
-
|
|
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
|
-
|
|
595
|
-
|
|
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,
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|
30
|
-
#
|
|
31
|
-
|
|
32
|
-
|
|
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":
|
|
63
|
-
|
|
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
|
|
69
|
-
"
|
|
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
|
-
|
|
73
|
+
(
|
|
74
|
+
"humanSummary, verdictCard, rationale, summary, finalVerdict, "
|
|
75
|
+
"recommendedNextSteps"
|
|
76
|
+
): (
|
|
73
77
|
"report presentation for the approver"
|
|
74
78
|
),
|
|
75
|
-
|
|
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(
|
|
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
|
|
127
|
-
|
|
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
|
|
145
|
+
return None
|
|
139
146
|
report = load_owned_object(plan_path, artifact="approved implementation plan")
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
|
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
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
-
|
|
180
|
-
|
|
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],
|
|
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
|
|
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
|