okstra 0.232.0 → 0.233.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -283
- package/dist/cli-registry.mjs +8 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.mjs +2 -17
- package/dist/lib/memory-auto-register.mjs.map +1 -1
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +36 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +279 -2
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +31 -41
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
- package/runtime/prompts/coding-preflight/clean-code.md +18 -20
- package/runtime/prompts/coding-preflight/overview.md +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -1
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
- package/runtime/python/okstra_ctl/code_review_census.py +93 -2
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +140 -15
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +33 -6
- package/runtime/python/okstra_ctl/manager_cli.py +122 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +42 -3
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +38 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +179 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
- package/runtime/python/okstra_ctl/run.py +43 -35
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_project/state.py +20 -0
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +58 -50
- package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
- package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +24 -0
- package/runtime/skills/okstra-memory/SKILL.md +1 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +93 -36
package/docs/cli.md
CHANGED
|
@@ -1,3 +1,214 @@
|
|
|
1
|
+
# okstra-run 입력 형식과 사용량 정책
|
|
2
|
+
|
|
3
|
+
새 실행은 run manifest에 `reportAuthoringFormat: "json-v1"`과 `usageAccountingPolicy: "advisory"`를 기록한다. 작성자 입력은 `reportNarrativePath`의 `.json` 파일에 허용된 작성자 소유 값만 쓰며, 설명 문자열에는 Markdown을 사용할 수 있다. 최종 보고서의 `schemaVersion`과 `reportContractVersion`은 `3.0`을 유지한다. 필드가 없는 기존 실행은 `markdown-v1`·`strict`로 읽으며, 알 수 없는 값은 거부한다.
|
|
4
|
+
|
|
5
|
+
`json-v1` 작성자 입력은 UTF-8 2,000,000바이트, 루트를 0으로 세고 스칼라 값을 포함한 깊이 32까지 받는다. 소유권 검사에서 방문한 필드 경로의 누적 길이는 64,000,000문자까지 허용한다. 초과·재귀 오류는 작성자 입력 결함으로 처리하며, 교정 결과도 같은 크기 제한을 통과한 뒤 게시한다. 보존된 교정 기준은 worker 결과 디렉터리의 일반 파일이어야 하고 심볼릭 링크는 거부한다. 이 한도는 작성자 JSON의 판독·교정 계약이며 최종 `data.json`의 크기 제한은 아니다.
|
|
6
|
+
|
|
7
|
+
다음 작성 중 입력 소비 명령은 선택 인자 `--run-manifest`를 받는다. 새 JSON 입력을 읽을 때는 해당 실행의 manifest를 함께 전달한다. 인자를 생략한 기존 호출은 Markdown 입력 경로를 유지하며, 확장자만 보고 JSON으로 전환하지 않는다. JSON 입력 경로는 manifest의 `reportNarrativePath`와 일치해야 한다.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
okstra plan-items extract --run-manifest <run-manifest> --narrative <writer-input> --output <items.json>
|
|
11
|
+
okstra plan-items validate --run-manifest <run-manifest> --narrative <writer-input> --items <items.json>
|
|
12
|
+
okstra option-votes gaps --task-manifest <task-manifest> --run-manifest <run-manifest> --narrative <writer-input> --json
|
|
13
|
+
okstra design-snapshot --run-manifest <run-manifest> --narrative <writer-input> --output <design-preparation.json>
|
|
14
|
+
okstra incremental-carry --run-manifest <run-manifest> --prev-data <previous.data.json> --cur-narrative <writer-input> --state <state.json> --prev-seq <seq> --carry-stages <csv> --reverify-stages <csv> --out-state <state.json>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`okstra token-usage <team-state> --write`는 해당 실행의 manifest에서 사용량 정책을 읽는다. `advisory`는 원인이 확인된 세션·청구량 부재를 진단으로 기록한다. 수집기의 기존 카운터는 유지하고, 보고서를 조립할 때 미수집 값과 불완전 합계를 `null`로 투영한다. 그 부재만으로 실제 작업 검증을 실패시키지는 않는다. 수집 생략·잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 계속 실패한다. 게시 후 재수집하거나 `--substitute-data <data.json>`을 지정해도 `advisory` 실행의 게시된 보고서는 덮어쓰지 않는다. `--write`를 사용한 재수집 결과는 team-state에 보존되며, `strict` 실행은 기존 동작을 유지한다.
|
|
18
|
+
|
|
19
|
+
호스트 지침은 wizard 확인 후 `orchestration.hostRulesPath`가 비어 있지 않을 때 첫 `render-bundle` 전에 읽는다. `implementation`·`implementation-planning`만 이 경로를 반환하며, 선언된 파일 누락은 오류다. 준비 후에는 동결 사본을 사용한다. [okstra-run 사용 규약](skills/okstra-run.md)과 [저장 계약](architecture/storage-model.md)을 함께 참고한다.
|
|
20
|
+
|
|
21
|
+
# 실행 묶음 준비
|
|
22
|
+
|
|
23
|
+
`okstra render-bundle`은 입력·지침·실행 기록을 준비하고 리드에게 제어를 넘깁니다. 새 리드 프로세스를 실행하지 않습니다. 입력 마법사에서 확정한 상태 파일을 직접 전달할 수 있습니다.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
okstra render-bundle --wizard-state-file <absolute-path> --summary-only
|
|
27
|
+
okstra render-bundle --wizard-state-file <absolute-path> --stage <confirmed-stage> --summary-only
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`--wizard-state-file`은 절대 경로를 받습니다. 코드는 상태를 한 번 판독하여 확정 여부·승인 범위를 확인하고, 역할·모델·반복 인자·빈 문자열을 기존 준비 함수에 전달합니다. 별도로 `--task-type`, `--task-brief`, `--role-model`, `--lead-runtime` 등을 섞으면 오류를 반환합니다. 기존 직접 인자 방식과 읽기 전용 `okstra wizard outcome --state-file <path>` 조회는 계속 지원합니다.
|
|
31
|
+
|
|
32
|
+
상태 파일 방식에서 추가할 수 있는 옵션은 출력 제어 `--summary-only`, 승인된 구현 연속 실행 안의 `--stage`, 기존 별도 사용자 확인을 거친 `--tdd-bypass`와 `--qa-waiver`입니다. 단계 선택은 기존 승인 범위로 제한하며, 두 면제 옵션은 기존 태스크 제한과 원장 검사를 그대로 따릅니다. 작업 준비에 필요한 호스트 실행 권한은 입력 마법사의 사용자 승인과 별개입니다.
|
|
33
|
+
|
|
34
|
+
`release-handoff`의 PR 템플릿 저장 요청은 확정된 프로젝트 루트와 저장 범위를 사용합니다. 저장 요청을 검증한 뒤 설정을 저장하며, 저장에 실패하면 실행 준비를 시작하지 않습니다. 설정 저장 후 준비가 실패하면 설정은 남고 오류 출력에서 그 사실을 알립니다. 자동으로 이전 값을 덮어쓰는 복구는 수행하지 않습니다.
|
|
35
|
+
|
|
36
|
+
새 확인 기록에는 설정의 키·값·저장 범위도 포함됩니다. 과거에 확정한 상태가 이 저장 요청을 기록하지 않았으면 새 경로는 자동 저장을 거부하고 해당 요청을 다시 확인하도록 안내합니다. 저장 요청이 없는 과거 확정 상태의 호환 경로는 유지합니다. 취소 응답이나 잘못된 형식의 승인 기록도 설정을 쓰기 전에 거부합니다.
|
|
37
|
+
|
|
38
|
+
스킬은 단일 실행의 준비가 성공한 뒤 상태 파일을 정리합니다. 연속 실행에서는 승인된 마지막 단계의 준비가 성공할 때까지 파일을 보존합니다. 파일이 사라지면 다음 단계 준비를 중단하고 입력 마법사를 다시 진행합니다. 이미 준비한 실행은 기존 실행 매니페스트(manifest)로 재개하며 상태 파일을 요구하지 않습니다. 응답 유실이나 부분 실패 뒤에는 기존 실행 상태를 먼저 확인하고 같은 준비 명령을 무조건 반복하지 않습니다.
|
|
39
|
+
|
|
40
|
+
이 경로의 강제 지점은 `wizard.launch.load_confirmed_launch()`, `render-bundle.prepareRenderBundle()`과 기존 `prepare_task_bundle()`이며, 상태 판독·전달 검사와 명령 경계 검사가 각각 이를 확인합니다.
|
|
41
|
+
|
|
42
|
+
# Implementation Trace commands
|
|
43
|
+
|
|
44
|
+
`okstra trace` manages a single-session Implementation Trace independently of
|
|
45
|
+
run manifests and the cross-verification lifecycle. All commands emit one JSON
|
|
46
|
+
object on stdout. Errors use a nonzero exit code and
|
|
47
|
+
`{"error":{"code":"...","message":"..."}}`.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
okstra trace new --slug <slug> [--project-root <dir>] [--task-key <key>] [--metadata <json-file>]
|
|
51
|
+
okstra trace status --slug <slug>
|
|
52
|
+
okstra trace status --path <file>
|
|
53
|
+
okstra trace advance --path <file> --step <id> [--host-runtime <id> --review <completion> ...] [--verdict pass|fail] [--approve "<user quote>"] [--evidence <json-file>] [--metadata <json-file>]
|
|
54
|
+
okstra trace reviewers --path <file> --host-runtime <id> [--count <n>]
|
|
55
|
+
okstra trace sync --path <file> [--task-key <key>] [--metadata <json-file>]
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`new` requires `.okstra/project.json`, accepts slugs matching
|
|
59
|
+
`^[a-z0-9]+(-[a-z0-9]+)*$`, and creates
|
|
60
|
+
`.okstra/traces/<slug>/<YYYYMMDD-HHMMSS>-<slug>.md`. Filename timestamps use local
|
|
61
|
+
time; `createdAt` includes its time-zone offset. The result is
|
|
62
|
+
`{path, slug, currentStep: "analysis"}`. A collision returns `TRACE_EXISTS`.
|
|
63
|
+
|
|
64
|
+
`status --slug` chooses the latest timestamped filename in that feature directory.
|
|
65
|
+
`--path` selects an explicit attempt. Status is read-only and returns
|
|
66
|
+
`{path, currentStep, steps, ids, nextAction, failStreak, commitPoint}`.
|
|
67
|
+
`nextAction` is `write`, `review`, `ask-user-decision`, `run-tests` or `done`.
|
|
68
|
+
|
|
69
|
+
`reviewers` works on the current review step. It returns the operation, duty,
|
|
70
|
+
`binding` text and reviewer `slots`. `analysis-review` and `spec-review` use the
|
|
71
|
+
`trace-scope-review` operation (`scope-critic`); `interface-review` uses
|
|
72
|
+
`trace-interface-review` (`interface-reviewer`). Slots come from the registered
|
|
73
|
+
model pool, ordered so models outside the host's own provider come first;
|
|
74
|
+
`--count` defaults to 1, must be a positive integer, and is capped by the
|
|
75
|
+
operation contract (`INVALID_ARGUMENT` otherwise). `independence` is
|
|
76
|
+
`cross-provider` when a slot's provider differs from the host's own provider,
|
|
77
|
+
otherwise `same-provider`. The binding names the trace path, step, next round,
|
|
78
|
+
the SHA-256 digest of the reviewed writing section's raw text (fenced blocks
|
|
79
|
+
included) and the host runtime.
|
|
80
|
+
|
|
81
|
+
`advance` accepts only the current step. A review passes in one of two ways:
|
|
82
|
+
|
|
83
|
+
- `--host-runtime <id>` with `--review <completion>`, repeated up to the
|
|
84
|
+
operation contract's count (the CLI also bounds the list at eight inputs).
|
|
85
|
+
Each completion of purpose `trace-review` must pass `verify-completion`, use
|
|
86
|
+
the step's duty and the same host runtime, carry the current binding text in
|
|
87
|
+
its prompt and return exactly one `Trace review verdict: pass|fail` line. Any
|
|
88
|
+
failing reviewer fails the review. When another provider is registered for
|
|
89
|
+
the role, at least one reviewer must use it. `--verdict` and `--approve` are
|
|
90
|
+
refused with `--review`. The step records
|
|
91
|
+
`review: {verdict, independence, reviewers}`.
|
|
92
|
+
- `--verdict pass --approve "<user quote>"`, the user-approval mode, which records
|
|
93
|
+
the quote under `approval`.
|
|
94
|
+
|
|
95
|
+
`--verdict fail` alone always fails the review. Failed reviews return to their
|
|
96
|
+
writing step and increment their failure streak. Three consecutive failures ask
|
|
97
|
+
the agent to obtain a user decision.
|
|
98
|
+
|
|
99
|
+
Writing sections use Markdown tables with fixed English headers:
|
|
100
|
+
|
|
101
|
+
- `analysis`: `Requirement` IDs (`R-NNN`) and a `Key` / `Value` table containing
|
|
102
|
+
`language`, `unitTestCommand`, `integrationTestCommand`, `typecheckCommand`.
|
|
103
|
+
- `spec`: `Spec item` / `Requirement` links.
|
|
104
|
+
- `interface-design`: `Use case` (`UC-NNN`) / `Requirement` links.
|
|
105
|
+
- `tests-red`: `Test` / `Use case` / `Kind` / `Path` rows; integration rows use
|
|
106
|
+
`integration` for `Kind`, with at least one integration test per UC.
|
|
107
|
+
|
|
108
|
+
Evidence files contain one object or an array of objects with `kind`
|
|
109
|
+
(`typecheck`, `unit`, `integration`), `command`, integer `exitCode`, `summary`,
|
|
110
|
+
and optional `failureCause`. The CLI adds `recordedAt`. `interface-code` requires
|
|
111
|
+
typecheck GREEN; `tests-red` requires unit and integration RED, each classified
|
|
112
|
+
`not-implemented`; `implementation` requires unit GREEN while integration may
|
|
113
|
+
remain RED; `integration` requires integration GREEN. Other failure causes are
|
|
114
|
+
`assertion`, `compile-error`, `import-error` and `other`.
|
|
115
|
+
|
|
116
|
+
The command updates JSON frontmatter and appends evidence blocks atomically.
|
|
117
|
+
The body belongs to the agent. `commitPoint` is set after `interface-code`,
|
|
118
|
+
`implementation` and `integration`; the command does not commit.
|
|
119
|
+
|
|
120
|
+
Contract errors include `PROJECT_NOT_INITIALIZED`, `INVALID_SLUG`,
|
|
121
|
+
`TRACE_EXISTS`, `TRACE_NOT_FOUND`, `TRACE_MALFORMED`, `STEP_MISMATCH`,
|
|
122
|
+
`APPROVAL_REQUIRED`, `TRACEABILITY_GAP`, `EVIDENCE_REJECTED`, `SECTION_EMPTY`,
|
|
123
|
+
`REVIEW_STALE` (a prompt lacks the current binding: the section, round, step,
|
|
124
|
+
trace or host changed, or the binding was not copied verbatim),
|
|
125
|
+
`REVIEW_REJECTED` (inauthentic completion, wrong duty or host, duplicate
|
|
126
|
+
completion, or a missing or repeated verdict line), `REVIEW_REQUIRED`,
|
|
127
|
+
`REVIEWER_NOT_INDEPENDENT` and `REVIEW_UNAVAILABLE` (the helper failed or timed
|
|
128
|
+
out after 60 seconds).
|
|
129
|
+
See the [skill guide](skills/okstra-tdd.md) for the agent workflow and the
|
|
130
|
+
boundary between validated inputs and agent judgment.
|
|
131
|
+
|
|
132
|
+
## Shared task history and discovery
|
|
133
|
+
|
|
134
|
+
A trace may carry an optional `task` object in version-1 frontmatter. `new
|
|
135
|
+
--task-key` links creation; `sync --task-key` attaches an older unlinked trace.
|
|
136
|
+
An attempt's key is immutable and belongs to the registered project. Metadata
|
|
137
|
+
JSON contains `title`, `summary`, `tags`, `changedFiles`, `references` and
|
|
138
|
+
`relatedTasks`; omitted fields retain their values. A linked integration
|
|
139
|
+
completion requires a nonempty functional `summary`, separate from test evidence.
|
|
140
|
+
Without binding options, existing standalone creation is unchanged.
|
|
141
|
+
|
|
142
|
+
A successful linked operation also returns `taskKey`, `task` and `taskSync`.
|
|
143
|
+
Trace publication precedes task projection. `TASK_SYNC_FAILED` includes
|
|
144
|
+
`traceSaved`, `path`, `taskKey` and a retry command. Query `status`, then use
|
|
145
|
+
`sync` to retry projection without advancing an already saved step. Read-only
|
|
146
|
+
status returns `taskSync: "pending"` when acknowledgment is unavailable. History
|
|
147
|
+
retains prior attempts; completion uses direct-work provenance with
|
|
148
|
+
`crossVerification: "not-performed"`, without a verification run or phase.
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
okstra task-list --query "<terms>" [--limit 20] [--after <task-key>]
|
|
152
|
+
okstra task-list --related-to <task-key> [--query "<terms>"] [--after <task-key>]
|
|
153
|
+
okstra task-show <task-key>
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Query terms are whitespace-separated, case-folded and AND-combined over titles,
|
|
157
|
+
summaries, metadata and linked trace text. Completed tasks are included. Related
|
|
158
|
+
results exclude the anchor itself and distinguish explicit `relatedTasks` in
|
|
159
|
+
either direction (`user-stated`) from shared tags, files or references
|
|
160
|
+
(`candidate`), with evidence. These operations do not write links or indexes.
|
|
161
|
+
Existing task filters still apply; ordinary listing retains its previous order.
|
|
162
|
+
Query pages use stable task-key order and return bounded `tasks`, `unavailable`,
|
|
163
|
+
`truncated` and `nextCursor` fields. Resume with `--after <nextCursor>`. An empty
|
|
164
|
+
page with a cursor does not establish that no matches exist. Unreadable, unsafe
|
|
165
|
+
or secret-containing sources are reported as `source-unavailable` without their
|
|
166
|
+
contents. Sources are checked for regular-file type before opening. Task details expose the latest trace and compact attempt history.
|
|
167
|
+
|
|
168
|
+
Metadata files are limited to 16 KiB; titles to 200 characters and summaries to
|
|
169
|
+
2,000. List limits are 20 tags of 64 characters, 100 changed files of 512,
|
|
170
|
+
20 references of 512 and 50 related task keys of 384. The retained task-level relation union is bounded by
|
|
171
|
+
the complete manifest byte limit; the 50-entry cap applies to each trace metadata
|
|
172
|
+
update. Task manifests are at most
|
|
173
|
+
2 MiB and retain at most 128 trace attempts. Queries accept 256 characters and
|
|
174
|
+
1–100 results (default 20), return 160-character previews, read a catalog up to
|
|
175
|
+
4 MiB / 1,000 candidates and inspect at most 64 tasks per page, including a
|
|
176
|
+
related anchor. Candidate and anchor source reads share a 16 MiB page budget
|
|
177
|
+
(with at most one overflow-probe byte); project configuration and catalog reads
|
|
178
|
+
retain their separate limits. Each source is limited to 2 MiB; response JSON to
|
|
179
|
+
256 KiB. A byte-budget stop preserves the unfinished candidate for the next page.
|
|
180
|
+
Pagination reports remaining candidates when an inspection or output bound is
|
|
181
|
+
reached. Enforcement lives in trace metadata validation and `okstra_ctl.task_query`;
|
|
182
|
+
regressions are in `tests-js/trace.test.mjs`, `tests/run/test_trace_tasks.py` and
|
|
183
|
+
`tests/run/test_task_query.py`.
|
|
184
|
+
|
|
185
|
+
## Trace capacity limits
|
|
186
|
+
|
|
187
|
+
Supported inputs and serialized outputs satisfy all applicable limits together:
|
|
188
|
+
|
|
189
|
+
| Boundary | Limit |
|
|
190
|
+
|---|---:|
|
|
191
|
+
| Trace file, UTF-8 | 2,097,152 bytes |
|
|
192
|
+
| Evidence JSON file; each language configuration read by trace | 262,144 bytes each |
|
|
193
|
+
| Complete trace, including frontmatter, blank lines and fences | 20,000 physical lines |
|
|
194
|
+
| Body table data across the document, excluding headers, separators and fenced examples | 10,000 rows |
|
|
195
|
+
| Table width | 16 columns |
|
|
196
|
+
| Raw requirement list; raw use-case list; raw evidence list | 1,000 entries each, before deduplication or expansion |
|
|
197
|
+
| Feature directory scan, including unrelated entries | 1,024 entries |
|
|
198
|
+
|
|
199
|
+
Bounded reads and structural checks reject an excess with `INPUT_LIMIT_EXCEEDED`
|
|
200
|
+
and a message identifying the limit. A directory excess returns no partial
|
|
201
|
+
selection. The same trace byte and structural limits apply before publication;
|
|
202
|
+
if approvals or evidence would exceed them, `advance` preserves every original
|
|
203
|
+
byte. Ordinary malformed input retains its existing error code. These language
|
|
204
|
+
configuration limits apply only to trace reads, not other commands' settings.
|
|
205
|
+
|
|
206
|
+
Local performance acceptance targets are a whole-command 95th percentile at
|
|
207
|
+
most 2,000 ms and maximum resident memory at most 192 MiB per process, measured
|
|
208
|
+
after three warm-ups over twenty samples on Apple M4 Max, Darwin 25.6.0 and Node
|
|
209
|
+
24.22.0, without another lock owner. Every capacity limit above is a prerequisite.
|
|
210
|
+
These are reference-environment QA targets, not universal CLI or CI guarantees.
|
|
211
|
+
|
|
1
212
|
# Implementation design-review inputs
|
|
2
213
|
|
|
3
214
|
New approved-plan implementation and final-verification preparations freeze
|
|
@@ -32,6 +243,72 @@ For a stage, pass its identified `--run-manifest <path>` to reuse the author's
|
|
|
32
243
|
frozen policy. A missing author-policy reference is unverified policy alignment;
|
|
33
244
|
do not infer a latest run or claim that independently captured policies match.
|
|
34
245
|
|
|
246
|
+
`okstra code-review assign --census <review-id>.census.md`는 프로젝트 `.okstra/` 아래의
|
|
247
|
+
전체 census를 축별 배정 census로 나눈다. 셀이 있는 축마다 같은 디렉터리에
|
|
248
|
+
`<review-id>.<axis>.census.md`를 쓰고, `Axis`·`Cells`·`Census` 줄을 축 순서
|
|
249
|
+
(`structural`, `semantic`, `general`, `state-and-tests`)대로 출력한다. 셀이 없는 축은
|
|
250
|
+
`Census: -`다. `## Cells` 밖의 줄(정책 digest, 리소스 선택, 규칙 목록)은 그대로 복사한다.
|
|
251
|
+
축별 셀이 서로 겹치지 않고 합치면 전체 census가 되는지 검사하며, 이미 있는 배정
|
|
252
|
+
파일은 내용이 같을 때만 재사용하고 다르면 종료 코드 2로 거부한다.
|
|
253
|
+
|
|
254
|
+
`okstra agent-prompt resolve-operation --operation <id>`는 작업의 팀마다 모델을 하나씩 정한다.
|
|
255
|
+
`--model <provider/model>`을 팀 순서대로 반복하면 그 모델을 쓰고, 없으면 프로젝트
|
|
256
|
+
`.okstra/project.json`의 `operationModels.<id>`, 그다음 `~/.okstra/config.json`의 같은 키,
|
|
257
|
+
그다음 공급자 어댑터의 기본 모델 순서로 고른다. 설정 범위는 서로 합치지 않는다. 팀마다
|
|
258
|
+
공급자가 달라야 하고, 작업 계약의 상한을 넘을 수 없으며, 공급자가 작업의 역할을 지원해야
|
|
259
|
+
한다. `--count`는 먼저 1부터 작업 계약의 상한까지인지 검사한다. `--model`과 함께 주면 개수가 같아야
|
|
260
|
+
하고, 설정 목록과 함께 주면 앞에서 그 수만큼 쓴다. `--host-runtime <host>`를 주면 슬롯마다 그 호스트에서 `cli-wrapper` 배정이
|
|
261
|
+
해석되는지도 확인한다. 출력의 각 슬롯에는 모델의 출처(`flag`, `project`, `global`,
|
|
262
|
+
`bundled`)가 붙는다. `--out <path>`는 같은 JSON 결과를 파일로도 쓰며, 그 파일이
|
|
263
|
+
`code-review prepare --slots`의 입력이다. 설정은 `okstra model operation set <id> <ref,ref...> --scope project|global`로
|
|
264
|
+
같은 검사를 거쳐 쓰고, `okstra model operation unset <id> --scope ...`로 지운다. `okstra model default|operation set|unset`은 설정 파일의 잠금을 잡은 채 읽고 쓰며,
|
|
265
|
+
해당 섹션 형태가 잘못되어 있으면 쓰지 않고 오류로 끝난다.
|
|
266
|
+
|
|
267
|
+
`okstra code-review prepare --review-id <id> --census <id>.census.md --review-policy <path>
|
|
268
|
+
--base <commit> --head <commit> --slots <slots.json> --brief <path> --host-runtime <host>`는
|
|
269
|
+
`.okstra/agent-invocations/code-review/<id>.census.md`를 축별로 나눈 뒤, 모델 팀과 축마다
|
|
270
|
+
`scope` 계산, 지시문 작성, 프롬프트 발행, 검증을 한 번에 한다. `--slots`는
|
|
271
|
+
`okstra agent-prompt resolve-operation --operation code-review --json`의 출력 파일이며, 팀마다
|
|
272
|
+
공급자가 달라야 한다. 지시문은 `--brief` 본문 뒤에 팀·축·census 경로와 그 축의 `scope` 출력을
|
|
273
|
+
붙인 것이다. 모든 호출은 `cli-wrapper` 실행기로 배정되고, invocation ID는
|
|
274
|
+
`<id>-t<team>-<axis>-a1`이다. 결과는 `<id>.batch.json`에 남고 항목마다 `Item:` 줄을 출력한다.
|
|
275
|
+
같은 입력으로 다시 실행하면 발행된 파일을 재사용하고, 내용이 다른 기존 파일이 있으면 거부한다.
|
|
276
|
+
`--previous-batch <이전 id>.batch.json`을 주면, 비교 기준과 공유 정책이 같을 때 같은 팀 순번·축·
|
|
277
|
+
공급자·모델의 이전 완료 기록(최신 시도부터)을 그 항목의 `scope`에 이전 입력으로 넘긴다. 공급자나
|
|
278
|
+
모델이 다른 팀, 기준이나 정책이 바뀐 회차는 이전 입력 없이 전체 검사한다.
|
|
279
|
+
|
|
280
|
+
`okstra code-review start --batch <id>.batch.json [--max-calls <n>]`는 아직 시작하지 않은
|
|
281
|
+
항목마다 감독 프로세스를 새 세션으로 띄우고 바로 반환한다. 감독 프로세스는 항목의 래퍼를
|
|
282
|
+
실행하면서 표준 출력과 표준 오류를 `.tmp/<invocation-id>.returned.txt`와 `.stderr.txt`에
|
|
283
|
+
쓰고, 래퍼가 끝나면 종료 코드를 `.tmp/<invocation-id>.exit.json`에 남긴다. 래퍼가 사전
|
|
284
|
+
검사에서 실패해 상태 파일을 쓰지 않은 경우도 이 기록으로 끝난 것을 안다. `--max-calls`를
|
|
285
|
+
주면 이 리뷰에서 이미 시작한 호출 수와 이번에 시작할 수의 합이 그 값을 넘을 때 아무것도
|
|
286
|
+
시작하지 않는다. 진행 상태는 `batch.json`이 아니라 잠금으로 보호하는 `<id>.state.json`에 둔다.
|
|
287
|
+
|
|
288
|
+
`okstra code-review await --batch <id>.batch.json --timeout-seconds <s>`는 끝난 항목을
|
|
289
|
+
응답 확정, 완료 기록 발행, 완료 확인 순서로 진행하고, 항목마다 그 축의 배정 census로 먼저
|
|
290
|
+
감사한다. 다른 축 셀에 쓴 행은 이 감사에서 알 수 없는 셀로 남는다. 모든 항목이 끝나면 팀마다
|
|
291
|
+
전체 census와 그 팀의 완료 기록으로 감사하고 `ALL_DONE`을 출력한다(빠짐 없이 끝나면 종료
|
|
292
|
+
코드 0, 실패·누락·알 수 없는 셀이 있으면 1). 시간이 지나면 `POLL_TIMEOUT`과 종료 코드 75로
|
|
293
|
+
끝나며 같은 명령을 다시 부르면 이어서 진행한다. 래퍼 종료 코드가 0이 아니거나 쓰기 감사
|
|
294
|
+
위반이 있거나 응답 본문이 비면 실패로, 감독 프로세스가 종료 기록 없이 사라지면 `stalled`로
|
|
295
|
+
기록한다. 팀·축마다 모든 시도의 완료 기록을 최신 시도부터 넣어 그 축의 첫 배정 census로
|
|
296
|
+
감사하므로, 같은 셀에 대한 정정된 행이 이전 행보다 먼저 선택된다. 셀별 판정 종류와 근거는
|
|
297
|
+
상태 파일의 축·팀 감사에 남는다. 두 경우는 팀·축마다 한 번씩 자동으로 다시 시도한다: 응답
|
|
298
|
+
본문 없이 0이 아닌 코드로 끝난 호출(재시도), 그리고 거절된 셀의 사유가 모두 행 작성 형식에 관한
|
|
299
|
+
시도(그 셀만 형식 수정, 지시문에 파서 사유를 넣는다). 형식 사유는 표 열, 중복 행·규칙 판정, N/A
|
|
300
|
+
별칭, 지적 ID 형식, Coverage Verdicts 절 밖에 없는 지적 본문, clean 근거의 표기다. 판정 행 누락은
|
|
301
|
+
응답에 판정이 하나도 없을 때만 형식 사유로 본다. 확인하지 않았거나 알 수 없는 규칙, 없는 파일·줄을
|
|
302
|
+
가리키는 근거는 형식 사유가 아니며 `gap-fill`로 처리한다. `start --max-calls`로 정한 한도를 넘으면
|
|
303
|
+
자동 시도도 하지 않는다.
|
|
304
|
+
|
|
305
|
+
`okstra code-review gap-fill --batch <id>.batch.json [--reject <team>:<cell-id> ...]`는 각 팀·축의
|
|
306
|
+
최신 시도에서 남은 셀(감사 누락 셀과 `--reject`로 거절한 셀)만 담은 census로 다음 시도를
|
|
307
|
+
준비하고 `batch.json`에 추가한다. 실패하거나 `stalled`가 된 시도는 그 시도의 셀 전체를 다시
|
|
308
|
+
요청한다. 지시문에는 남은 셀과 사유, 이전 시도의 확인된 응답이 들어간다. 직전 보완 시도가
|
|
309
|
+
요청받은 셀을 하나도 닫지 못한 팀·축은 새 시도를 만들지 않고 `NO_PROGRESS: <team>/<axis>`를
|
|
310
|
+
출력한다(종료 코드 1). 새 시도는 `start`로 시작한다.
|
|
311
|
+
|
|
35
312
|
`okstra code-review scope --review-policy <snapshot> ...` uses captured source
|
|
36
313
|
bodies for its rule fingerprints. New standalone `code-reviewer` materialization
|
|
37
314
|
requires `--review-policy`, `--review-census`, `--review-base`, and `--review-head`.
|
|
@@ -39,7 +316,7 @@ Repeat `--review-resource` with any explicit selections made for the census.
|
|
|
39
316
|
The materializer reads the fixed tree, validates canonical assigned rules, and
|
|
40
317
|
includes the selected frozen rules, calibration and assigned census itself.
|
|
41
318
|
Do not duplicate their bodies in an instruction file or replace them with live
|
|
42
|
-
installed paths.
|
|
319
|
+
installed paths. Every specialist of every model team uses the same shared policy.
|
|
43
320
|
|
|
44
321
|
Standalone reviews audit source and Git changes after execution. A source or
|
|
45
322
|
index mutation prevents a successful review without restoring user changes.
|
|
@@ -151,7 +428,7 @@ okstra doyouknow list --after <nextCursor>
|
|
|
151
428
|
```
|
|
152
429
|
|
|
153
430
|
`sync` reads existing Memory Book entries, manager registrations, assignments,
|
|
154
|
-
notes and
|
|
431
|
+
notes, snapshots and manager journals, and tasks in manager-registered projects. It preserves the
|
|
155
432
|
original files. `list` reads the cached sources without collecting them again;
|
|
156
433
|
`--source`, `--scope`, `--limit` and `--after` select the returned page. JSON is
|
|
157
434
|
the default; all commands also accept `--text`. Partial collection exits 1 with
|
|
@@ -7,12 +7,11 @@ Use this matrix before changing high-risk repo contracts. Update the source file
|
|
|
7
7
|
| Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
|
|
8
8
|
| Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
|
|
9
9
|
| Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/skills/<name>.md`, `docs/skills/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs` |
|
|
10
|
-
| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests
|
|
10
|
+
| Change manager contract | `scripts/okstra_ctl/manager_*.py`, `skills/okstra-manager/SKILL.md`, `docs/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests/doyouknow/test_manager_sources.py`, `tests/doyouknow/test_okstra_manager_journal.py` |
|
|
11
11
|
| Change a skill's behaviour | `skills/<name>/SKILL.md`, `docs/skills/<name>.md` (every Guarantees row names its enforcement or says `unenforced`) | unenforced |
|
|
12
12
|
| Add phase | `scripts/okstra_ctl/phases/catalog.py`, `scripts/okstra_ctl/workflow.py`, `scripts/okstra_ctl/phases/<package>/` (`profile.md`, `profile.json`, `spec.md`, policy, report assets and tests), common assembly in `validators/` | workflow and validation contract tests |
|
|
13
13
|
| Change role requirements | `scripts/okstra_ctl/phases/<package>/profile.json`, `scripts/okstra_ctl/role_requirements.py` | role requirement contract tests |
|
|
14
14
|
| Change phase policy | `scripts/okstra_ctl/phases/<package>/`, its `spec.md`, and the common caller; continuation decisions belong in `prompts/lead/phase-routing.md` | phase-local tests |
|
|
15
15
|
| Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
|
|
16
|
-
| Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`cli.mjs`, `baseline.mjs`, `config.mjs`, `markdown.mjs`, and the shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`cli`, `config`, `markdown`, and `skill`) |
|
|
17
16
|
|
|
18
17
|
`runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.
|
|
@@ -20,6 +20,20 @@
|
|
|
20
20
|
|
|
21
21
|
## 1. Project identity
|
|
22
22
|
|
|
23
|
+
`skills/okstra-tdd/SKILL.md` adds a single-session implementation flow independent
|
|
24
|
+
of the cross-verification lifecycle. Its TypeScript state authority is
|
|
25
|
+
`src/commands/trace/trace.mts`, registered as `okstra trace` in
|
|
26
|
+
`src/cli-registry.mts`. It uses `src/lib/report-language.mts` and the built-in
|
|
27
|
+
`templates/trace/trace.template.md`, retaining attempts under `.okstra/traces/`.
|
|
28
|
+
`src/commands/trace/task-link.mts` connects saved traces to the Python task
|
|
29
|
+
projection in `scripts/okstra_ctl/trace_tasks.py`. Registration and completion
|
|
30
|
+
reuse `direct_work.py`; bounded read-only task discovery lives in `task_query.py`
|
|
31
|
+
and is exposed by `task_list_cli.py`. Task manifests retain latest trace metadata
|
|
32
|
+
and compact attempt history without a verification run. Regression owners are
|
|
33
|
+
`tests/run/test_trace_tasks.py`, `tests/run/test_task_query.py` and
|
|
34
|
+
`tests-js/trace.test.mjs`; run `npm run test:js`
|
|
35
|
+
separately from `npm run check`.
|
|
36
|
+
|
|
23
37
|
`okstra` is a host-aware, multi-provider cross-verification runtime distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs one neutral lifecycle core through Claude Code, Codex, or an explicit external adapter around a stable task key.
|
|
24
38
|
|
|
25
39
|
Current baseline:
|
|
@@ -55,8 +69,6 @@ okstra/
|
|
|
55
69
|
│ ├── okstra_vendor/ vendored Jinja2 / MarkupSafe (final-report rendering)
|
|
56
70
|
│ └── lib/okstra/ Bash helpers for okstra.sh
|
|
57
71
|
├── skills/ User-invocable skills (15); `_fragments/` holds shared marker blocks
|
|
58
|
-
├── .agents/skills/ Codex repo-local maintainer skills
|
|
59
|
-
├── .claude/skills/ Claude Code project-only mirror-sync surface
|
|
60
72
|
├── .codex/hooks.json Codex project lifecycle hooks
|
|
61
73
|
├── agents/ native Claude execution-adapter definitions
|
|
62
74
|
├── prompts/ launch/profile contracts, duty catalog, wizard prompt JSON
|
|
@@ -65,8 +77,6 @@ okstra/
|
|
|
65
77
|
├── validators/ run / brief / schedule / view validators
|
|
66
78
|
├── tools/build.mjs source → runtime sync
|
|
67
79
|
├── tools/sync-skill-fragments.mjs expand shared fragment blocks into skills/*/SKILL.md
|
|
68
|
-
├── tools/korean-sources/ maintainer-only Korean mirror drift report
|
|
69
|
-
├── config/korean-sources.json configured English Markdown source roots
|
|
70
80
|
├── runtime/ generated install payload; do not edit directly
|
|
71
81
|
├── tests/ pytest unit suite
|
|
72
82
|
├── tests-e2e/ Bash end-to-end scenarios
|
|
@@ -265,7 +275,7 @@ Important modules:
|
|
|
265
275
|
| `self_mock_signals.py` | self-mock signal SSOT — language-keyed regexes (`SIGNALS`), the `EXT_TO_LANG` extension map, and the waiver-matching mechanics both gates share — `selfmock_path_key` (the one path-normalization), `waiver_entry_key` (the `(file, line, <discriminator>)` triple, with the hand-typed line coerced to `int`) and `partition_waived_entries` (the split into still-failing vs waived). Gate A passes the discriminator `signal`, gate B `mutant`; one definition means the two cannot disagree about whether a waiver matches a finding. The signals are each ported from a `prompts/coding-preflight/languages/<lang>.md` "Self-mock signals to refuse" bullet with the source `doc_keyword` retained so a drift guard fails when doc and module diverge. Patterns stay deliberately narrow (only the "stub the subject's own method, then assert the stub" shape and reaching into the subject's privates; subject identity is never inferred beyond the literal `sut` token). The static detector `validators/detect_self_mock.py`, the drift guard and `mutation_probe.py` MUST import from here; four documented shapes needing subject identity no regex has are left to the mutation gate (`mutation_probe.py`) |
|
|
266
276
|
| `mutation_probe.py` | gate B of the self-mock gate — the tool-agnostic mutation probe. `ADAPTERS` maps an `EXT_TO_LANG` language key to an adapter (`ts_js` → Stryker, `python` → Cosmic Ray, `rust` → cargo-mutants, `java`/`kotlin` → PIT, which reports `unsupported` because its SCM scoping is a Maven-only goal and the report↔path mapping is unverified). The Python adapter activates only when the worktree has both an installed `cosmic-ray` executable and `cosmic-ray.toml`; Okstra never installs it. It verifies that `module-path` covers every changed Python target and that no target is excluded, snapshots the configured Python source bytes and modes, restores them after every run, and filters the JSONL dump to diff-added lines. A completed session with no applicable operator on a changed line is `nothing-to-verify`; malformed configuration, command/report failures, incomplete trials, and failed source restoration are blocking `integrity-inspection` results. `run_probe` owns everything that must not differ between tools: production-source selection, the refusal to run on an empty target set, the requirement that the diff name EVERY changed source, the adapter result-shape check and the user-acknowledged waiver application; adapters only parse. `evaluate` counts a mutant only when it covers a line the diff added or modified, and records the pre-cap `survivedTotal` so a trimmed report cannot be fully waived to PASS. Anything that stops a real inspection — no adapter, tool not installed, unreadable report, unknown outcome word, no conclusive trial, a diff that misses a changed source — answers `unsupported(<reason>)`, never `PASS`. `classify_reason` is the 3-class SSOT (capability-gap / nothing-to-verify / integrity-inspection, unknown → integrity) read by BOTH the cross-language merge here and the blocking decision in `validators/validate-run.py` |
|
|
267
277
|
| `run_context.py` | Per-task mutex, run context and run-input persistence; `consumers_mutex` helper for atomic `consumers.jsonl` writes |
|
|
268
|
-
| `path_hints.py` |
|
|
278
|
+
| `path_hints.py` | `run-context`·`active-run-context`의 schemaVersion `2.0` `identity` + `pathHints` 저장과 기존 평면 경로 키 복원을 담당한다. 작성자 형식과 사용량 정책도 보존해 재개 시 입력 경로와 정책을 설치본 기본값으로 바꾸지 않는다 |
|
|
269
279
|
| `consumers.py` | Append-only `consumers.jsonl` writer + reader — records which `implementation` runs consumed which `implementation-planning` stage |
|
|
270
280
|
| `implementation_outcome.py` | Artifact-derived reconstruction of the implementation phase outcome — reads `runs/implementation/carry/stage-<N>.json` + `consumers.jsonl` + the approved Stage Map to derive `phaseOutcome.implementation`, and when every stage has pass-grade carry evidence it raises `workflow.nextRecommendedPhase.status` to `ready` (keeping the `contract-violated` audit information). It never picks the phase — `phase` is left as the last stage's report routing settled it, and the status is raised only while `phase` is non-empty |
|
|
271
281
|
| `paths.py` | Path/sequence computation for task/run artifacts (including recap directory/log paths) |
|
|
@@ -303,9 +313,9 @@ Important modules:
|
|
|
303
313
|
| `report_execution_evidence.py` | Derives each verifier's execution evidence references and final-verification command rows from the verification execution records, and compares a report's references with them for the phase validators |
|
|
304
314
|
| `report_assembly.py` | Validates the role-owned report inputs and publishes the contract 3.0 record once (assembled in a temp file, then atomically promoted); a bad input aborts with owner / artifact path / field path / reason and preserves the existing `data.json` |
|
|
305
315
|
| `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
|
|
306
|
-
| `report_narrative.py` |
|
|
307
|
-
| `report_corrections.py` |
|
|
308
|
-
| `report_synthesis_packet.py` |
|
|
316
|
+
| `report_narrative.py` | 계약 3.0의 작성자 소유 입력을 manifest의 `reportAuthoringFormat`에 따라 읽고 쓴다. 새 `json-v1`은 표준 JSON 객체와 Markdown 설명 문자열을 사용하며, 기존 `markdown-v1` 줄 문법도 유지한다. 중첩된 기계 소유 필드까지 소유권을 검사한다 |
|
|
317
|
+
| `report_corrections.py` | 리더의 교정 원장(`report-writer-corrections-<task-type>-<seq>-a<N>.json`)을 작성자 소유 스키마·태스크 계약으로 검사하고 선언된 입력 형식으로 교정한다. `replace`·`remove`만 있는 원장은 기계적으로 적용하며, JSON 입력의 필드 이름과 경로는 JSON 키로 안내한다. 호출자는 `agent/prompt_cli/corrections.py`다 |
|
|
318
|
+
| `report_synthesis_packet.py` | 작성자에게 전달할 자료의 소유자·경로·digest와 저작 계약을 `report-writer-synthesis-packet-<task-type>-<seq>.{json,md}`로 동결한다. `initial_prompt_materialization.py`가 디스패치 시 생성하며, 선언된 작성 형식과 해당 확장자를 사용한다. 게시 시 `report_assembly.py`가 원본 digest를 대조한다. 스키마는 `schemas/report-synthesis-packet-v1.0.schema.json`이다 |
|
|
309
319
|
| `approval_decisions.py` | Lead-owned approval-decision input ledger — `disposition` (`select`/`accept-risk`/`request-revision`/`reject`), reach, scope effect, and classification invariants (`correctness-critical`/`noncritical-dissent`/`user-decision`) |
|
|
310
320
|
| `design_snapshot.py` | Builds the design-surface-detector-owned snapshot from the report narrative — reproducible design surfaces plus conservative `PREP-NNN` preparation items (delegates surface detection to `design_surfaces.py`) |
|
|
311
321
|
| `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the full reading copy — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
|
|
@@ -339,6 +349,8 @@ Important modules:
|
|
|
339
349
|
| `resolve_task_key.py` | shared skill helper resolving a bare task-id → `task-catalog.json` candidate entries (`okstra resolve-task-key`) |
|
|
340
350
|
| `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
|
|
341
351
|
| `code_review_target.py` | `okstra code-review` argument and output boundary. Stage mode reads recorded stage targets; branch mode requires an explicit frozen base. Routes citation checks, verified coverage and conservative follow-up scope proposals. Read-only: it never creates the review directory |
|
|
352
|
+
| `code_review_invocation.py` | binds a standalone code review to its assigned census, selected frozen review policy and fixed comparison range, so the prompt carries applicable rules and calibration |
|
|
353
|
+
| `code_review_integrity.py` | records immutable source/Git integrity evidence (baseline before, audit after execution) for standalone review completions; source, protected-input or semantic Git index changes fail the run. Detects changes after execution; not an OS write sandbox |
|
|
342
354
|
| `code_review_scope.py` | Proposes per-reviewer carry candidates using verified prior coverage, frozen range and rule/policy fingerprints, and recorded source dependencies. Current reviewers still attest the impact boundary and publish current verdicts |
|
|
343
355
|
| `session.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
|
|
344
356
|
| `pane_reclaim.py` | resolves which runs of the current project still hold a non-terminal dispatch, so the `SessionStart(compact)` hook can re-inject the pane-cleanup obligation for them. The signal is the newest `team-state` per run directory, not the central run index — an in-session run never appears there (ADR-0011). Imports the status split from the `dispatch_state.NON_TERMINAL_WORKER_STATUSES` SSOT |
|
|
@@ -406,7 +418,7 @@ Important modules:
|
|
|
406
418
|
| `task_target.py` | shared helper resolving `task-key → (task_root, project_root)` (`resolve_task_root`) |
|
|
407
419
|
| `contract_refreeze.py` | re-freezes a running run's frozen contracts in the installed format. A run freezes its duty/role/common contracts at start and pins their digest, so installing a release that changed the contract format leaves that run unable to produce another prompt (`run duty snapshot catalog digest does not match`). Backs `okstra agent-prompt refreeze-contracts`, rewrites the frozen copies and the manifest digest only, and never touches a prompt, result or ledger |
|
|
408
420
|
| `operation_invocation.py` | prepares an Okstra-owned LLM operation that runs outside `okstra-run` — the operation contract (`agents/operations/<id>.json`) owns the duty and the worker count, and the role is derived from that duty's `roleId`, so a skill passes the operation name instead of assembling role/provider/model itself (ADR-0017). Backs `okstra agent-prompt resolve-operation` |
|
|
409
|
-
| `phases/catalog.py` |
|
|
421
|
+
| `phases/catalog.py` | 13개 태스크의 패키지·프로필·보고서 자산과 호스트 지침 필요 여부를 한 자산 루트에서 해석한다. `implementation`·`implementation-planning`만 호스트 지침을 선언하며, 선언한 파일이 없으면 오류를 반환한다. phase 모듈을 import하지 않고 `{{INCLUDE:...}}`도 해석한다 |
|
|
410
422
|
| `phases/final_verification/` | Final-verification policy and assets: `profile.md`/`profile.json` (recorded under the logical paths `prompts/profiles/final-verification.*`), `spec.md` (process note and guarantees), `entry.py` (verification-target request, snapshot writer, prepare-flag checks), `validation.py` (added-surface, verdict, and scope checks that `validate-run` calls before its routing check), `wizard.py` (whole-task pick condition), `target.py` (`acquire_final_verification_target()`: chooses single-stage, containing-stage, or integrated whole-task target behind one task-key mutex), `report.py` (HTML view builder and `verificationScope` reader), and `report_assets/` (report body templates). Its `tests/` directory is collected by pytest and left out of the runtime copy |
|
|
411
423
|
| `report_template_loader.py` | Jinja loader for report templates: a logical name owned by a migrated phase opens from that phase's `report_assets/`, and every other name opens from `templates/reports` |
|
|
412
424
|
| `contract_graph.py`, `contract_graph_cli.py` | runtime-contract graph loader + cross-reference/dependency-closure validator and its `okstra contract-check --root <dir> (--profile\|--operation)` CLI boundary. Loads the agent contract schemas (`common`/`role`/`duty`/`profile`/`operation`), validates known role capabilities, and reports the dependency closure with per-file `path`/`schemaVersion`/`sha256`; an invalid contract raises `ContractGraphError` |
|
|
@@ -438,7 +450,7 @@ Important modules:
|
|
|
438
450
|
| `worker_artifacts.py` | the roster worker-id vocabulary and the artifact paths derived from it |
|
|
439
451
|
| `worker_state.py` | `okstra worker-state transition` — the authoritative status transitions of one persisted team-state |
|
|
440
452
|
| `usage_cells.py` | how a token, cost, or duration figure reads in a report cell; shared by the Markdown and HTML report renderers |
|
|
441
|
-
| `report_contract.py` |
|
|
453
|
+
| `report_contract.py` | 공개 final-report 태스크 계약과 작성자 형식의 정본이다. 보고서 스키마는 `3.0`을 유지하며, `json-v1`·`markdown-v1`과 확장자를 해석한다. 형식 필드가 없는 기존 실행은 `markdown-v1`이고, 알 수 없는 형식이나 3.0 이전 계약의 `json-v1`은 거부한다 |
|
|
442
454
|
|
|
443
455
|
> `i18n.py` (the final-report i18n dictionary loader + Jinja2 lookup) is an intentionally undocumented internal helper — it is a render helper that users and contributors do not need to know about in the canonical docs, so it is excluded from the module map.
|
|
444
456
|
|
|
@@ -477,10 +489,10 @@ Project resolver and read-only state helpers:
|
|
|
477
489
|
Token/cost accounting:
|
|
478
490
|
|
|
479
491
|
- provider adapters: `claude.py`, `codex.py`, `antigravity.py`, `grok.py`, `kimi.py`, `zai/adapter.py` (`grok.py` reads the Grok Build session docs under `~/.grok/sessions/<percent-encoded-cwd>/`, taking cumulative tokens from the last `params.update.usage.modelUsage` snapshot in `updates.jsonl`; `zai/adapter.py` wraps the Claude Code executor for GLM workers — reads `ZAI_API_KEY` from the process env or the current user's `~/.env`, runs each child against `https://api.z.ai/api/anthropic` with `--setting-sources ""`, attests the served model only from response `message.model`, and prices usage at Z.ai's public API rates for `glm-5.3` / `glm-5.3-flash`)
|
|
480
|
-
-
|
|
492
|
+
- 집계: `collect.py`, `blocks.py`, `jsonl_io.py`, `paths.py`. `policy.py`가 manifest의 `usageAccountingPolicy`와 진단을 공유한다. 새 실행의 `advisory`는 확인된 사용량 부재와 불완전 합계를 `null`·진단으로 남기며, 필드가 없는 기존 실행은 `strict`를 유지한다. 잘못된 값·귀속 모호성·예상하지 못한 수집 오류는 실패로 남는다.
|
|
481
493
|
- incremental scan cache: `cursor.py` (`$OKSTRA_HOME/cache/token-usage/` byte cursor + usage event extracts; bypass with `--no-cache`)
|
|
482
494
|
- pricing: `pricing.py`
|
|
483
|
-
-
|
|
495
|
+
- 보고서 반영: `report.py`. `advisory` 실행의 게시 후 재수집은 team-state에만 저장하며, 게시된 `data.json`·HTML을 덮어쓰지 않는다.
|
|
484
496
|
- CLI: `cli.py` via `scripts/okstra-token-usage.py` and `okstra token-usage`
|
|
485
497
|
|
|
486
498
|
### 4.6 `prompts/`
|
|
@@ -514,7 +526,7 @@ Token/cost accounting:
|
|
|
514
526
|
|
|
515
527
|
### 4.8 `schemas/`
|
|
516
528
|
|
|
517
|
-
`schemas/final-report-v3.0.schema.json
|
|
529
|
+
현재 final-report 데이터 계약은 `schemas/final-report-v3.0.schema.json`이다. 작성자는 새 `json-v1`이나 기존 `markdown-v1`의 허용 필드만 작성하고, 조립기가 역할별 기계 소유 입력을 결합해 `final-report-<task-type>-<seq>.data.json`을 원자적으로 게시한다. 두 렌더러가 읽기용 Markdown과 태스크별 HTML을 독립적으로 생성한다. 형식 변경으로 최종 스키마 버전을 올리지 않으며, 기존 v1·v2 판독도 유지한다.
|
|
518
530
|
|
|
519
531
|
The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
|
|
520
532
|
|
|
@@ -541,7 +553,7 @@ Optional (v1.0 backward-compatible) top-level keys:
|
|
|
541
553
|
|
|
542
554
|
14 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
|
|
543
555
|
|
|
544
|
-
|
|
556
|
+
여러 스킬이 공유하는 bash 호출·CLI 버전 확인·Python 준비 문구는 `skills/_fragments/*.md`를 정본으로 두고 `tools/sync-skill-fragments.mjs`가 각 `SKILL.md`의 fragment 마커 사이에 전개한다. `node tools/sync-skill-fragments.mjs --check`로 불일치를 확인한다. 구현·계획의 호스트 절차는 스킬 본문에 미리 전개하지 않는다. wizard가 선택한 태스크의 `orchestration.hostRulesPath`를 반환하면 첫 준비 전에 읽고, 준비 후에는 동결된 `instruction-set/host-orchestration-rules.md`를 사용한다. 설치된 스킬도 이 절차에는 설치 런타임의 지침 경로를 사용한다.
|
|
545
557
|
|
|
546
558
|
| Skill | User-invocable | Role |
|
|
547
559
|
|---|---:|---|
|
|
@@ -578,28 +590,6 @@ These are provider-neutral contracts rendered into every dispatch prompt, not ho
|
|
|
578
590
|
- Tests replace operating-system resources and wall-clock waits with controlled doubles.
|
|
579
591
|
- A higher-layer test keeps only the minimum positive flow needed to detect wiring failures.
|
|
580
592
|
|
|
581
|
-
### 4.13 `tools/korean-sources/`
|
|
582
|
-
|
|
583
|
-
The maintainer-only Korean review mirrors. The tool reports which mirrors have
|
|
584
|
-
drifted and checks a translation's structure; a maintainer session does the
|
|
585
|
-
translating and the writing. Nothing here observes edits or runs on its own.
|
|
586
|
-
|
|
587
|
-
| File | Role |
|
|
588
|
-
|---|---|
|
|
589
|
-
| `cli.mjs` | The three commands: `status`, `validate --source`, `mark --source` |
|
|
590
|
-
| `baseline.mjs` | Drift report and the source/mirror hash pair recorded at the last sync |
|
|
591
|
-
| `config.mjs` | `config/korean-sources.json` validation and source↔mirror path mapping |
|
|
592
|
-
| `markdown.mjs` | Protected-Markdown structure comparison behind `validate` |
|
|
593
|
-
| `path-safety.mjs` | Symlink-refusing repository reads and atomic writes |
|
|
594
|
-
|
|
595
|
-
Source and mirror hold the same document in two languages, so they never hash
|
|
596
|
-
alike and drift cannot be read from the two files alone. `mark` records the pair
|
|
597
|
-
of hashes in `.project-docs/ko-sources/.sync-baseline.json`, which is the only
|
|
598
|
-
state the tool keeps. Maintainers follow `tools/korean-sources/workflow.md`; the
|
|
599
|
-
paired local skills only delegate to it and are not published user skills.
|
|
600
|
-
|
|
601
|
-
---
|
|
602
|
-
|
|
603
593
|
## 5. Key runtime modules
|
|
604
594
|
|
|
605
595
|
### 5.1 Prepare flow
|
|
@@ -648,9 +638,9 @@ Current report pipeline:
|
|
|
648
638
|
|
|
649
639
|
1. Analysis workers write worker result files and the separate audit sidecars named by `Audit sidecar path`.
|
|
650
640
|
2. The lead writes semantic groups; the convergence engine persists working state, per-round plans/results, an optional critic transition, and then a validated `state/convergence-<task-type>-<seq>.json` terminal state: schema v1.4 when newly finalized, or an unchanged historical final schema v1.0, v1.1, v1.2, or v1.3 returned by `reuse-final`.
|
|
651
|
-
3.
|
|
652
|
-
4.
|
|
653
|
-
5.
|
|
641
|
+
3. 작성자는 manifest의 `reportNarrativePath`에 허용된 값을 쓴다. 새 `json-v1`의 경로는 `worker-results/report-writer-narrative-<task-type>-<seq>.json`이며, 기존 `markdown-v1`은 `.md` 경로를 유지한다. Phase 7이 최종 schema v3 보고서를 조립한다.
|
|
642
|
+
4. 구현 계획에서는 `okstra plan-items extract`가 `P-*` 큐를 추출하고 `validate`가 작성자 입력 또는 기존 `data.json`과 대조한다. 새 JSON 입력에는 `--run-manifest`를 함께 전달한다. 분석자별 계획 본문 검증 라운드는 별도로 유지한다.
|
|
643
|
+
5. 게시 시 사용량·비용을 보고서에 투영하며, 새 `advisory` 실행의 미수집 값과 불완전 합계는 `null`·진단으로 남긴다. 게시 후 재수집은 team-state만 갱신한다. 읽기용 Markdown은 `okstra render-final-report`가 `templates/reports/final-report-v2.template.md`에서 필요할 때 생성한다.
|
|
654
644
|
6. `scripts/okstra-render-report-views.py` independently selects one of twelve dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks the record and the human HTML. A quick Markdown input retains its legacy conditional path.
|
|
655
645
|
|
|
656
646
|
For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
|
|
@@ -661,7 +651,7 @@ Both Markdown and HTML are derived, not authoring sources. The schema is the con
|
|
|
661
651
|
|
|
662
652
|
- `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
|
|
663
653
|
- `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
|
|
664
|
-
- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
|
|
654
|
+
- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and locked, atomic `modelDefaults` and `operationModels` writes. No inference call. `operation_invocation.py` reads `operationModels` and selects an operation's models for `resolve-operation`.
|
|
665
655
|
- `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
|
|
666
656
|
|
|
667
657
|
---
|
|
@@ -764,7 +754,7 @@ When changing code, keep these docs in sync:
|
|
|
764
754
|
- New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
|
|
765
755
|
- New phase/profile behavior: update the phase directory under `scripts/okstra_ctl/phases/` and its `spec.md`, plus `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
|
|
766
756
|
|
|
767
|
-
Edit
|
|
757
|
+
Edit canonical Markdown sources directly. Maintainer-local notes under `.project-docs/` are neither published nor committed.
|
|
768
758
|
|
|
769
759
|
---
|
|
770
760
|
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -6,7 +6,7 @@ These execution procedures apply only to the worker authorized to change project
|
|
|
6
6
|
|
|
7
7
|
- [ ] Read project instructions, configured conventions and every selected resource for this turn. Apply the shared [quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) before editing.
|
|
8
8
|
- [ ] Before adding a unit, search identifiers, behavior, callers, domain literals, error strings and returned-data shapes; read the candidates. Record search terms, nearest implementation and `extend <path:line>` or `new (nothing covers <behavior>)`. Name-only uniqueness does not establish absence; missing survey evidence leaves the addition unfinished.
|
|
9
|
-
- [ ] **Tests planned:** identify retained or extended tests and
|
|
9
|
+
- [ ] **Tests planned:** identify retained or extended tests for changed core behavior and meaningful failure outcomes under [Testing discipline](clean-code.md#testing-discipline) and [test reuse](clean-code.md#reuse-tests-before-adding-coverage). Select mutation checks only where needed under those criteria or an explicit project requirement. Record uncovered outcomes, any permitted waiver and its unverified scope there.
|
|
10
10
|
- [ ] Apply the detailed checks in `clean-code.md`, including mutation/state, security, testing, third-party wrappers and failure paths where applicable.
|
|
11
11
|
- [ ] If the hexagonal overlay is selected, apply its H1–H6 criteria and stated exceptions under the policy precedence in `overview.md`.
|
|
12
12
|
|