okstra 0.236.0 → 0.237.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/docs/architecture/storage-model.md +1 -0
- package/docs/architecture.md +1 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
- package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
- package/runtime/python/okstra_ctl/manager_cli.py +42 -5
- package/runtime/python/okstra_ctl/manager_launch.py +60 -1
- package/runtime/python/okstra_ctl/manager_store.py +45 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
- package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
- package/runtime/python/okstra_ctl/wizard/state.py +4 -1
- package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
- package/runtime/python/okstra_ctl/worker_audit_ledger.py +9 -3
- package/runtime/skills/okstra-manager/SKILL.md +8 -2
- package/runtime/skills/okstra-setup/SKILL.md +34 -5
- package/runtime/skills/okstra-setup/references/project-config.md +19 -0
|
@@ -707,6 +707,7 @@ Storage authority:
|
|
|
707
707
|
- `manager.json`: manager identity and schema version.
|
|
708
708
|
- `projects.json`: the projectId / projectRoot / role / tags registered with the manager. `projectRoot` must be an existing directory, and setup-equivalent registration is performed only when project-local `.okstra/project.json` is absent.
|
|
709
709
|
- `manifest.json`, `children.json`, `directives.jsonl`: manager-owned plan, child assignment, and shared/project directives.
|
|
710
|
+
- `children.json`의 하위 작업 행은 `task run --base-ref`로 받은 `baseRef`와, `task register-session`이 기록한 `session`(`address`, `name`, `registeredAt`)을 가집니다. `task run`은 옵션이 없으면 그 `baseRef`를 쓰고, 없으면 같은 프로젝트 형제 행들이 모두 같은 `baseRef`를 가질 때만 그 값을 씁니다. 세션 등록이 값을 바꾸면 작업 `events.jsonl`에 `child-session-registered` 행을 남깁니다.
|
|
710
711
|
- `group.json`: the task group's original name and creation time, written by `new task-group` and `new task`. The directory name is a slug and cannot give the name back.
|
|
711
712
|
- `split-plan.json`: the last tracker split plan `task split` applied. The briefs it produced live in each child project's `.okstra/briefs/`, and the children it registered carry `ticketId`, `briefPath`, `scope` and `recommendedPhase` in `children.json`.
|
|
712
713
|
- `snapshots.json`: a read-side snapshot that `task sync` imports from the child project's `.okstra`. It is not the source of truth for project state.
|
package/docs/architecture.md
CHANGED
|
@@ -154,7 +154,7 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
|
|
|
154
154
|
- `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
|
|
155
155
|
- Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical: one file per run at `runs/<task-type>/prompts/lead-execution-prompt-<task-type>-<seq>.md`. No Claude-named copy is written — `resources.claudeExecutionPromptPath` in the run manifest is a key alias that resolves to that same file for historical consumers.
|
|
156
156
|
- Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
|
|
157
|
-
- [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and
|
|
157
|
+
- [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install`, creates `project.json`, and offers to save worker defaults through the `okstra-run` worker settings mode.
|
|
158
158
|
- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
|
|
159
159
|
- Twelve skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-discussion/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-chat/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, `skills/okstra-code-review/SKILL.md`, and `skills/okstra-explain-flow/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, multi-agent discussions that settle requirements before planning, cross-project manager task coordination, global Memory Book storage/search, global chat rooms, schedule support, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`.
|
|
160
160
|
- Wrapper transcripts are written at `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`.
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -103,7 +103,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
103
103
|
| `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" |
|
|
104
104
|
| `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" |
|
|
105
105
|
| `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" |
|
|
106
|
-
| `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
|
+
| `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>] [--blocks next-phase]` | Open an approval blocker after the user confirmed it; `--candidate-ref` names the implementation option a split-vote decision accepts; `--blocks next-phase` records a decision of a phase whose profile says `Blocks=next-phase` (the default is `approval`) | this contract "User confirmation before an approval blocker" |
|
|
107
107
|
| `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" |
|
|
108
108
|
| `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" |
|
|
109
109
|
| `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" |
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
- every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
|
|
1
|
+
- every `Kind=decision` clarification row is recorded by the lead in the approval decision ledger — one `okstra approval-decision open --ledger <approvalDecisionsPath>` call per row, before report assembly runs. The row's `Blocks` value is the call's `--blocks`: `approval` by default, so pass `--blocks next-phase` for every row the phase profile or `_common-contract.md` assigns `Blocks=next-phase`. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` `_decision_row` refuses any other value. Assembly reads `clarificationItems[]` from that ledger and from nowhere else, so a decision that exists only as narrative prose reaches no reader and no answer channel: `okstra user-response` cannot offer a row the ledger never carried, and the HTML prints "No further decision is needed" over the top of it. Each option is an object with eight fields:
|
|
2
2
|
- `role` — `recommended` for the single best answer, `alternative` for the rest. Exactly one option per row is `recommended`.
|
|
3
3
|
- `answer` — the choice itself, phrased so the user can pick it as-is. Keep it to a short phrase (roughly 120 characters); the reasoning and the consequences have their own fields below.
|
|
4
4
|
- `rationale` — why this option is on the board, as long as the reason needs.
|
|
@@ -11,6 +11,7 @@ from dataclasses import dataclass
|
|
|
11
11
|
from pathlib import Path
|
|
12
12
|
from typing import Any, Mapping, Sequence
|
|
13
13
|
|
|
14
|
+
from .clarification_items.dispositions import USER_INPUT_BLOCKS
|
|
14
15
|
from .clarification_items.sidecars import (
|
|
15
16
|
sidecar_answers,
|
|
16
17
|
attached_response_sections,
|
|
@@ -57,6 +58,10 @@ SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
|
|
|
57
58
|
CLASSIFICATIONS = frozenset(
|
|
58
59
|
{"user-decision", "noncritical-dissent", "correctness-critical"}
|
|
59
60
|
)
|
|
61
|
+
# A phase without an approval gate records its decisions as next-phase blockers
|
|
62
|
+
# (`_common-contract.md` reporter-confirmation precondition); both are the values
|
|
63
|
+
# the gates read as waiting on user input.
|
|
64
|
+
DECISION_BLOCKS = tuple(sorted(USER_INPUT_BLOCKS))
|
|
60
65
|
_FORBIDDEN_BY_CLASSIFICATION = {
|
|
61
66
|
"correctness-critical": frozenset({"select"}),
|
|
62
67
|
"noncritical-dissent": frozenset({"select"}),
|
|
@@ -214,7 +219,12 @@ def _decision_row(
|
|
|
214
219
|
expected_form: str, classification: str, origin: str,
|
|
215
220
|
user_confirmation: str, unblock_condition: str,
|
|
216
221
|
recommended_disposition: str, options: Sequence[DecisionOption],
|
|
222
|
+
blocks: str = "approval",
|
|
217
223
|
) -> dict[str, Any]:
|
|
224
|
+
if blocks not in DECISION_BLOCKS:
|
|
225
|
+
raise ApprovalDecisionError(
|
|
226
|
+
f"invalid blocks: {blocks!r}. Allowed values: " + ", ".join(DECISION_BLOCKS)
|
|
227
|
+
)
|
|
218
228
|
if classification not in CLASSIFICATIONS:
|
|
219
229
|
raise ApprovalDecisionError(f"invalid classification: {classification}")
|
|
220
230
|
_reject_off_enum(origin, "origin", "ClarificationOrigin")
|
|
@@ -232,7 +242,7 @@ def _decision_row(
|
|
|
232
242
|
"kind": "decision",
|
|
233
243
|
"statement": _required(statement, "statement"),
|
|
234
244
|
"expectedForm": _required(expected_form, "expected_form"),
|
|
235
|
-
"blocks":
|
|
245
|
+
"blocks": blocks,
|
|
236
246
|
"origin": _required(origin, "origin"),
|
|
237
247
|
"userConfirmation": _required(user_confirmation, "user_confirmation"),
|
|
238
248
|
"approval": {
|
|
@@ -250,7 +260,7 @@ def open_decision(
|
|
|
250
260
|
classification: str, origin: str, user_confirmation: str,
|
|
251
261
|
unblock_condition: str, recommended_disposition: str,
|
|
252
262
|
options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
|
|
253
|
-
candidate_ref: str = "",
|
|
263
|
+
candidate_ref: str = "", blocks: str = "approval",
|
|
254
264
|
) -> None:
|
|
255
265
|
row = _decision_row(
|
|
256
266
|
clarification_id=clarification_id, ticket_id=ticket_id,
|
|
@@ -258,6 +268,7 @@ def open_decision(
|
|
|
258
268
|
classification=classification, origin=origin,
|
|
259
269
|
user_confirmation=user_confirmation, unblock_condition=unblock_condition,
|
|
260
270
|
recommended_disposition=recommended_disposition, options=options,
|
|
271
|
+
blocks=blocks,
|
|
261
272
|
)
|
|
262
273
|
ledger = _ledger(ledger_path, task_key, task_type, run_seq)
|
|
263
274
|
active = ledger.get("activeClarifications")
|
|
@@ -487,6 +498,15 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
|
|
|
487
498
|
"candidate's splitAcceptance may cite only a decision opened for it."
|
|
488
499
|
),
|
|
489
500
|
)
|
|
501
|
+
parser.add_argument(
|
|
502
|
+
"--blocks",
|
|
503
|
+
choices=DECISION_BLOCKS,
|
|
504
|
+
default="approval",
|
|
505
|
+
help=(
|
|
506
|
+
"what the open row withholds: approval (the default) or next-phase, "
|
|
507
|
+
"for a phase without an approval gate"
|
|
508
|
+
),
|
|
509
|
+
)
|
|
490
510
|
|
|
491
511
|
|
|
492
512
|
_CLI_EPILOG = r"""Usage:
|
|
@@ -28,6 +28,7 @@ from .manager_store import (
|
|
|
28
28
|
list_projects,
|
|
29
29
|
list_task_groups,
|
|
30
30
|
list_tasks,
|
|
31
|
+
register_child_session,
|
|
31
32
|
remove_child,
|
|
32
33
|
remove_task,
|
|
33
34
|
remove_task_group,
|
|
@@ -58,7 +59,7 @@ _LIST_ROWS = {
|
|
|
58
59
|
def render_manager_text(command: str, payload: dict | list[dict]) -> str:
|
|
59
60
|
"""manager 모델 표면에 승인된 식별자와 상태만 투영한다."""
|
|
60
61
|
allowed = {"init", "discover-projects", "new-project", "new-task-group", "new-task",
|
|
61
|
-
"task-assign", "task-note", "task-sync", "task-status", "task-run", "task-split",
|
|
62
|
+
"task-assign", "task-register-session", "task-note", "task-sync", "task-status", "task-run", "task-split",
|
|
62
63
|
"list-managers", "list-projects", "list-task-groups", "list-tasks", "view",
|
|
63
64
|
"task-update", "task-remove-child", "remove-project", "remove-task", "remove-task-group",
|
|
64
65
|
"log", "journal-add", "resume"}
|
|
@@ -80,7 +81,9 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
|
|
|
80
81
|
("Backend", "backend"),
|
|
81
82
|
("Worker dispatch backend", "workerDispatchBackend"),
|
|
82
83
|
("Project root", "projectRoot"), ("Context path", "contextPath"),
|
|
83
|
-
("Shell command", "shellCommand"), ("
|
|
84
|
+
("Shell command", "shellCommand"), ("Base ref", "baseRef"),
|
|
85
|
+
("Base ref source", "baseRefSource"), ("Manager session", "managerSession"),
|
|
86
|
+
("View path", "viewPath"),
|
|
84
87
|
("View URL", "viewUrl")):
|
|
85
88
|
if key in payload:
|
|
86
89
|
rows.append(line(label, payload.get(key)))
|
|
@@ -92,6 +95,7 @@ def render_manager_text(command: str, payload: dict | list[dict]) -> str:
|
|
|
92
95
|
"new-project": (("Projects", "projects"),),
|
|
93
96
|
"new-task": (("Manifest", "manifest"), ("Children", "children")),
|
|
94
97
|
"task-assign": (("Children", "children"),),
|
|
98
|
+
"task-register-session": (("Children", "children"),),
|
|
95
99
|
"task-sync": (("Children", "children"),),
|
|
96
100
|
}
|
|
97
101
|
for label, key in structures.get(command, ()):
|
|
@@ -245,11 +249,15 @@ def _render_manager_status(payload: dict) -> list[str]:
|
|
|
245
249
|
("current phase", "currentPhase"), ("work status", "workStatus"),
|
|
246
250
|
("summary", "summaryBucket"), ("project linked", "projectLinked"),
|
|
247
251
|
("ticket", "ticketId"), ("brief path", "briefPath"),
|
|
248
|
-
("report path", "latestReportRecordPath"),
|
|
252
|
+
("report path", "latestReportRecordPath"), ("base ref", "baseRef"),
|
|
249
253
|
("changed since sync", "changedSinceSync"), ("error", "error")):
|
|
250
254
|
if key in child:
|
|
251
255
|
value = child.get(key)
|
|
252
256
|
rows.append(line(f"Child {index} {label}", ("yes" if value else "no") if isinstance(value, bool) else value))
|
|
257
|
+
session = child.get("session") if isinstance(child.get("session"), dict) else {}
|
|
258
|
+
for label, key in (("session address", "address"), ("session name", "name")):
|
|
259
|
+
if session.get(key):
|
|
260
|
+
rows.append(line(f"Child {index} {label}", session[key]))
|
|
253
261
|
if isinstance(child.get("discussion"), dict):
|
|
254
262
|
rows.extend(_render_discussion(index, child["discussion"]))
|
|
255
263
|
return rows
|
|
@@ -332,7 +340,8 @@ _CLI_EPILOG = r"""Usage:
|
|
|
332
340
|
okstra manager task sync --manager-id <id> --task-group <task-group> --task-id <task-id>
|
|
333
341
|
okstra manager task assign --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id>
|
|
334
342
|
okstra manager task note --manager-id <id> --task-group <task-group> --task-id <task-id> --scope <shared|project> --body <text>
|
|
335
|
-
okstra manager task
|
|
343
|
+
okstra manager task register-session --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <id>] --session <address> [--session-name <name>]
|
|
344
|
+
okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--base-ref <ref>] [--manager-session <address>]
|
|
336
345
|
okstra manager task split --manager-id <id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
|
|
337
346
|
okstra manager task update --manager-id <id> --task-group <task-group> --task-id <task-id> [--objective <text>] [--common-brief <path>] [--progress-mode <manual|auto>]
|
|
338
347
|
okstra manager task remove-child --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <id>] [--confirm]
|
|
@@ -411,6 +420,15 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
411
420
|
assign.add_argument("--tag", action="append", default=[])
|
|
412
421
|
assign.add_argument("--assignment", default="")
|
|
413
422
|
|
|
423
|
+
session = task_sub.add_parser("register-session")
|
|
424
|
+
session.add_argument("--manager-id", required=True)
|
|
425
|
+
session.add_argument("--task-group", required=True)
|
|
426
|
+
session.add_argument("--task-id", required=True)
|
|
427
|
+
session.add_argument("--project-id", required=True)
|
|
428
|
+
session.add_argument("--child-task-id", default=None)
|
|
429
|
+
session.add_argument("--session", required=True)
|
|
430
|
+
session.add_argument("--session-name", default="")
|
|
431
|
+
|
|
414
432
|
note = task_sub.add_parser("note")
|
|
415
433
|
note.add_argument("--manager-id", required=True)
|
|
416
434
|
note.add_argument("--task-group", required=True)
|
|
@@ -426,6 +444,8 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
426
444
|
run.add_argument("--task-id", required=True)
|
|
427
445
|
run.add_argument("--child-task-id", default=None)
|
|
428
446
|
run.add_argument("--allow-completed", action="store_true")
|
|
447
|
+
run.add_argument("--base-ref", default="")
|
|
448
|
+
run.add_argument("--manager-session", default="")
|
|
429
449
|
|
|
430
450
|
split = task_sub.add_parser("split")
|
|
431
451
|
split.add_argument("--manager-id", required=True)
|
|
@@ -513,7 +533,7 @@ def _manager_state_changed(args: argparse.Namespace) -> bool:
|
|
|
513
533
|
if args.command == "task":
|
|
514
534
|
if args.task_command == "remove-child":
|
|
515
535
|
return args.confirm
|
|
516
|
-
return args.task_command in ("assign", "note", "sync", "run", "split", "update")
|
|
536
|
+
return args.task_command in ("assign", "register-session", "note", "sync", "run", "split", "update")
|
|
517
537
|
return False
|
|
518
538
|
|
|
519
539
|
|
|
@@ -583,6 +603,21 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
583
603
|
),
|
|
584
604
|
args.json,
|
|
585
605
|
)
|
|
606
|
+
elif args.command == "task" and args.task_command == "register-session":
|
|
607
|
+
_emit(
|
|
608
|
+
"task-register-session",
|
|
609
|
+
register_child_session(
|
|
610
|
+
home,
|
|
611
|
+
args.manager_id,
|
|
612
|
+
args.task_group,
|
|
613
|
+
args.task_id,
|
|
614
|
+
args.project_id,
|
|
615
|
+
address=args.session,
|
|
616
|
+
name=args.session_name,
|
|
617
|
+
child_task_id=args.child_task_id,
|
|
618
|
+
),
|
|
619
|
+
args.json,
|
|
620
|
+
)
|
|
586
621
|
elif args.command == "task" and args.task_command == "note":
|
|
587
622
|
_emit(
|
|
588
623
|
"task-note",
|
|
@@ -612,6 +647,8 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
612
647
|
args.project_id,
|
|
613
648
|
child_task_id=args.child_task_id,
|
|
614
649
|
allow_completed=args.allow_completed,
|
|
650
|
+
base_ref=args.base_ref,
|
|
651
|
+
manager_session=args.manager_session,
|
|
615
652
|
),
|
|
616
653
|
args.json,
|
|
617
654
|
)
|
|
@@ -19,7 +19,15 @@ from .manager_paths import (
|
|
|
19
19
|
snapshots_json_path,
|
|
20
20
|
task_manifest_path,
|
|
21
21
|
)
|
|
22
|
-
from .manager_store import
|
|
22
|
+
from .manager_store import (
|
|
23
|
+
ManagerError,
|
|
24
|
+
_now_iso,
|
|
25
|
+
_read_json,
|
|
26
|
+
_read_json_default,
|
|
27
|
+
_session_address,
|
|
28
|
+
_write_json,
|
|
29
|
+
record_event,
|
|
30
|
+
)
|
|
23
31
|
from .manager_sync import _snapshot_child, summary_bucket
|
|
24
32
|
|
|
25
33
|
|
|
@@ -94,6 +102,32 @@ def _sibling_snapshots(snapshot: dict, target_task_key: str) -> list[dict]:
|
|
|
94
102
|
]
|
|
95
103
|
|
|
96
104
|
|
|
105
|
+
def _launch_base_ref(children: dict, child: dict, project_id: str, requested: str) -> tuple[str, str]:
|
|
106
|
+
"""The base ref a child's first phase branches from, and where it came from.
|
|
107
|
+
|
|
108
|
+
A sibling's ref is reused only within the same project and only when every sibling that
|
|
109
|
+
recorded one agrees; refs of different repositories, or a split choice, are not guesses to make.
|
|
110
|
+
A child whose worktree is registered and checked out ignores the ref. One whose registry row is
|
|
111
|
+
stale and whose branch is gone is rebuilt from this ref instead of the recorded commit.
|
|
112
|
+
"""
|
|
113
|
+
if requested.strip():
|
|
114
|
+
ref = requested.strip()
|
|
115
|
+
if ref.startswith("-") or any(c.isspace() for c in ref):
|
|
116
|
+
raise ManagerError(f"--base-ref must be a branch, tag or commit: {requested!r}")
|
|
117
|
+
return ref, "argument"
|
|
118
|
+
if str(child.get("baseRef") or ""):
|
|
119
|
+
return str(child["baseRef"]), "child"
|
|
120
|
+
sibling_refs = {
|
|
121
|
+
str(row.get("baseRef"))
|
|
122
|
+
for row in children.get("children", [])
|
|
123
|
+
if isinstance(row, dict) and row is not child
|
|
124
|
+
and row.get("projectId") == project_id and row.get("baseRef")
|
|
125
|
+
}
|
|
126
|
+
if len(sibling_refs) == 1:
|
|
127
|
+
return sibling_refs.pop(), "sibling"
|
|
128
|
+
return "", "none"
|
|
129
|
+
|
|
130
|
+
|
|
97
131
|
def _discussion_follow_up_brief(snapshot: dict, target_task_key: str) -> Path | None:
|
|
98
132
|
"""`okstra discussion follow-up-brief` 가 이 하위 task 에 쓴 브리프.
|
|
99
133
|
|
|
@@ -120,6 +154,7 @@ def _render_context(
|
|
|
120
154
|
directives: list[dict],
|
|
121
155
|
siblings: list[dict],
|
|
122
156
|
discussion_ref: dict | None,
|
|
157
|
+
manager_session: str,
|
|
123
158
|
) -> str:
|
|
124
159
|
lines = [
|
|
125
160
|
"# Okstra Manager Child Context",
|
|
@@ -153,6 +188,18 @@ def _render_context(
|
|
|
153
188
|
f"- requirements: {', '.join(discussion_ref['requirementIds'])}",
|
|
154
189
|
"- The brief pins this revision; a newer revision applies only when the user adopts it.",
|
|
155
190
|
""])
|
|
191
|
+
if manager_session:
|
|
192
|
+
lines.extend([
|
|
193
|
+
"## Manager Reporting",
|
|
194
|
+
"",
|
|
195
|
+
f"- manager session: {manager_session}",
|
|
196
|
+
"",
|
|
197
|
+
f"Send the manager session a message naming child task-key {child_task_key} and this session's own "
|
|
198
|
+
"address when this run starts, and one naming the task key when each phase ends; "
|
|
199
|
+
"then wait for the manager before starting the next phase.",
|
|
200
|
+
"Approval gates stay with this session's user.",
|
|
201
|
+
"",
|
|
202
|
+
])
|
|
156
203
|
lines.extend(["## Manager Directives", ""])
|
|
157
204
|
for row in directives:
|
|
158
205
|
lines.append(f"- [{row.get('scope')}] {row.get('body')}")
|
|
@@ -204,6 +251,8 @@ def _record_launch_prepared(
|
|
|
204
251
|
}
|
|
205
252
|
)
|
|
206
253
|
child["launch"] = launch
|
|
254
|
+
if packet["baseRefSource"] == "argument":
|
|
255
|
+
child["baseRef"] = packet["baseRef"]
|
|
207
256
|
_write_json(children_json_path(home, manager_id, task_group, task_id), children)
|
|
208
257
|
record_event(
|
|
209
258
|
events_jsonl_path(home, manager_id, task_group, task_id),
|
|
@@ -250,6 +299,8 @@ def build_launch_packet(
|
|
|
250
299
|
*,
|
|
251
300
|
child_task_id: str | None = None,
|
|
252
301
|
allow_completed: bool = False,
|
|
302
|
+
base_ref: str = "",
|
|
303
|
+
manager_session: str = "",
|
|
253
304
|
now: str | None = None,
|
|
254
305
|
) -> dict:
|
|
255
306
|
manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
|
|
@@ -265,6 +316,8 @@ def build_launch_packet(
|
|
|
265
316
|
_validate_child_task_key(child, target_task_key)
|
|
266
317
|
project_root = _validated_project_root(project)
|
|
267
318
|
current = _current_child_state(project_root, child, target_task_key, allow_completed=allow_completed)
|
|
319
|
+
resolved_base_ref, base_ref_source = _launch_base_ref(children, child, project_id, base_ref)
|
|
320
|
+
manager_session = _session_address(manager_session, "--manager-session") if manager_session.strip() else ""
|
|
268
321
|
created_at = now or _now_iso()
|
|
269
322
|
brief_path = (Path(str(child["briefPath"])) if child.get("briefPath")
|
|
270
323
|
else _discussion_follow_up_brief(snapshot, target_task_key))
|
|
@@ -279,6 +332,7 @@ def build_launch_packet(
|
|
|
279
332
|
directives=_directives_for_project(directives, project_id),
|
|
280
333
|
siblings=_sibling_snapshots(snapshot, target_task_key),
|
|
281
334
|
discussion_ref=discussion_ref,
|
|
335
|
+
manager_session=manager_session,
|
|
282
336
|
),
|
|
283
337
|
encoding="utf-8",
|
|
284
338
|
)
|
|
@@ -302,6 +356,8 @@ def build_launch_packet(
|
|
|
302
356
|
run_args.extend(["--task-type", str(recommended)])
|
|
303
357
|
if brief_path is not None:
|
|
304
358
|
run_args.extend(["--task-brief", str(brief_path)])
|
|
359
|
+
if resolved_base_ref:
|
|
360
|
+
run_args.extend(["--base-ref", resolved_base_ref])
|
|
305
361
|
run_args += [
|
|
306
362
|
"--directive",
|
|
307
363
|
f"{MANAGER_CONTEXT_DIRECTIVE_PREFIX}{context_path}",
|
|
@@ -319,6 +375,9 @@ def build_launch_packet(
|
|
|
319
375
|
"command": command,
|
|
320
376
|
"runArgs": run_args,
|
|
321
377
|
"shellCommand": shlex.join([command, *run_args]),
|
|
378
|
+
"baseRef": resolved_base_ref,
|
|
379
|
+
"baseRefSource": base_ref_source,
|
|
380
|
+
"managerSession": manager_session,
|
|
322
381
|
"createdAt": created_at,
|
|
323
382
|
}
|
|
324
383
|
if discussion_ref:
|
|
@@ -486,6 +486,51 @@ def assign_child(
|
|
|
486
486
|
return payload
|
|
487
487
|
|
|
488
488
|
|
|
489
|
+
def _session_address(value: str, option: str) -> str:
|
|
490
|
+
text = value.strip()
|
|
491
|
+
if not text or text.startswith("-") or any(c in text for c in "\r\n"):
|
|
492
|
+
raise ManagerError(f"{option} must be a non-empty single-line session address")
|
|
493
|
+
return text
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
def register_child_session(
|
|
497
|
+
home: Path,
|
|
498
|
+
manager_id: str,
|
|
499
|
+
task_group: str,
|
|
500
|
+
task_id: str,
|
|
501
|
+
project_id: str,
|
|
502
|
+
*,
|
|
503
|
+
address: str,
|
|
504
|
+
name: str = "",
|
|
505
|
+
child_task_id: str | None = None,
|
|
506
|
+
now: str | None = None,
|
|
507
|
+
) -> dict:
|
|
508
|
+
"""Record which host session runs a child task.
|
|
509
|
+
|
|
510
|
+
The address is what the manager sends messages to; a host may rename the session on restart
|
|
511
|
+
while keeping the address, so the name is informational only.
|
|
512
|
+
"""
|
|
513
|
+
_read_json(task_manifest_path(home, manager_id, task_group, task_id))
|
|
514
|
+
payload = _load_children(home, manager_id, task_group, task_id)
|
|
515
|
+
child = _select_child_for_assignment(payload["children"], project_id, task_group, child_task_id)
|
|
516
|
+
current = child.get("session") if isinstance(child.get("session"), dict) else {}
|
|
517
|
+
if any(c in name for c in "\r\n"):
|
|
518
|
+
raise ManagerError("--session-name must be a single line")
|
|
519
|
+
requested = {"address": _session_address(address, "--session"),
|
|
520
|
+
"name": name.strip() or str(current.get("name") or "")}
|
|
521
|
+
changes = _field_changes(current, requested)
|
|
522
|
+
if changes:
|
|
523
|
+
created_at = now or _now_iso()
|
|
524
|
+
child["session"] = {**requested, "registeredAt": created_at}
|
|
525
|
+
_write_json(children_json_path(home, manager_id, task_group, task_id), payload)
|
|
526
|
+
record_event(
|
|
527
|
+
events_jsonl_path(home, manager_id, task_group, task_id),
|
|
528
|
+
{"event": "child-session-registered", "createdAt": created_at,
|
|
529
|
+
"taskKey": str(child.get("taskKey") or ""), "changes": changes},
|
|
530
|
+
)
|
|
531
|
+
return payload
|
|
532
|
+
|
|
533
|
+
|
|
489
534
|
def append_directive(
|
|
490
535
|
home: Path,
|
|
491
536
|
manager_id: str,
|
|
@@ -872,7 +872,7 @@ never recorded, and the round is scored on the items that remain.
|
|
|
872
872
|
**Explanation**: <2-3 sentences>
|
|
873
873
|
**Dependencies**: {"complete": false, "itemIds": [], "paths": []}
|
|
874
874
|
|
|
875
|
-
Keep the detailed Note and Explanation. Declare all direct and transitive plan-item and whole-file evidence dependencies. Set `complete` to true only when that boundary is known. Include source files behind references. External or dynamic evidence, unlisted narrative dependencies and unresolved references keep `complete` false. This declaration controls reuse eligibility, not the verdict itself. Missing and malformed declarations are treated as unknown by `verdict_blocks._block` and `plan_item_evidence.review_fingerprint`.
|
|
875
|
+
Keep the detailed Note and Explanation. Declare all direct and transitive plan-item and whole-file evidence dependencies. Set `complete` to true only when that boundary is known. Include source files behind references. External or dynamic evidence, unlisted narrative dependencies and unresolved references keep `complete` false. This declaration controls reuse eligibility, not the verdict itself. The run manifest and the task manifest are rewritten on every dispatch; the runtime neither snapshots them nor counts them in the closure, and their review facts (worker assignments, contracts) enter the reuse fingerprint directly. Cite the plan items, project source files, plan narrative or analysis packet that the verdict rests on instead. Missing and malformed declarations are treated as unknown by `verdict_blocks._block` and `plan_item_evidence.review_fingerprint`.
|
|
876
876
|
|
|
877
877
|
### P-Opt-2
|
|
878
878
|
...
|
|
@@ -3,6 +3,7 @@ from __future__ import annotations
|
|
|
3
3
|
|
|
4
4
|
import hashlib
|
|
5
5
|
import json
|
|
6
|
+
import posixpath
|
|
6
7
|
import re
|
|
7
8
|
import stat
|
|
8
9
|
from collections.abc import Mapping, Sequence
|
|
@@ -31,6 +32,7 @@ class ReviewInputs(TypedDict):
|
|
|
31
32
|
complete: bool
|
|
32
33
|
planContext: dict[str, Any]
|
|
33
34
|
priorReviewHashes: dict[str, str]
|
|
35
|
+
runOwned: dict[str, Any]
|
|
34
36
|
|
|
35
37
|
|
|
36
38
|
def _digest(value: object) -> str:
|
|
@@ -63,6 +65,22 @@ def _file_snapshot(root: Path, name: str) -> FileSnapshot | None:
|
|
|
63
65
|
return None
|
|
64
66
|
|
|
65
67
|
|
|
68
|
+
def _run_owned(manifest: Mapping[str, Any]) -> dict[str, Any]:
|
|
69
|
+
"""The run and task manifests, which every dispatch rewrites.
|
|
70
|
+
|
|
71
|
+
A reviewer may cite them, but a snapshot of one changes with every dispatch, and the review
|
|
72
|
+
facts they hold (assignments, contracts) already enter the `context` digest. Other files in the
|
|
73
|
+
run directory, such as the plan narrative, stay evidence.
|
|
74
|
+
"""
|
|
75
|
+
names = (manifest.get("runManifestPath"), manifest.get("taskManifestPath"))
|
|
76
|
+
return {"files": sorted({posixpath.normpath(str(name)) for name in names if name})}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _is_run_owned(name: str, owned: Mapping[str, Any]) -> bool:
|
|
80
|
+
path = posixpath.normpath(name)
|
|
81
|
+
return any(path == file or path.endswith("/" + file) for file in owned.get("files", []))
|
|
82
|
+
|
|
83
|
+
|
|
66
84
|
def _payload_paths(value: object) -> set[str]:
|
|
67
85
|
if isinstance(value, str):
|
|
68
86
|
return {value} if value and not any(c in value for c in "\n`*") else set()
|
|
@@ -118,9 +136,12 @@ def capture_review_inputs(
|
|
|
118
136
|
"plan_items.py", "plan_item_evidence.py", "plan_review_context.py", "phases/implementation_planning/authoring.py",
|
|
119
137
|
"phases/implementation_planning/instructions/plan-body-verification.md",
|
|
120
138
|
)})
|
|
139
|
+
run_owned = _run_owned(manifest)
|
|
140
|
+
paths = {name for name in paths if not _is_run_owned(name, run_owned)}
|
|
121
141
|
files = {name: _file_snapshot(root, name) for name in sorted(paths)}
|
|
122
142
|
return {
|
|
123
143
|
"version": 1,
|
|
144
|
+
"runOwned": run_owned,
|
|
124
145
|
"planContext": metadata,
|
|
125
146
|
"priorReviewHashes": {str(row["id"]): str(row.get("verifiedReviewHash", "")) for row in previous_rows},
|
|
126
147
|
"items": {str(item["id"]): dict(item) for item in items},
|
|
@@ -180,6 +201,8 @@ def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tu
|
|
|
180
201
|
declared = _vote_dependencies(graph.get(key), inputs.get("workers", []))
|
|
181
202
|
if declared is None:
|
|
182
203
|
return None
|
|
204
|
+
owned = inputs.get("runOwned") or {}
|
|
205
|
+
declared = (declared[0], {name for name in declared[1] if not _is_run_owned(name, owned)})
|
|
183
206
|
if any(not inputs.get("files", {}).get(name)
|
|
184
207
|
or inputs["files"][name]["hash"] == "absent" for name in declared[1]):
|
|
185
208
|
return None
|
|
@@ -198,7 +221,8 @@ def _dependency_closure(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> tu
|
|
|
198
221
|
)
|
|
199
222
|
for field in ("files", "plannedPaths"):
|
|
200
223
|
paths.update(_payload_paths(payload.get(field)))
|
|
201
|
-
|
|
224
|
+
owned = inputs.get("runOwned") or {}
|
|
225
|
+
return item_ids, {name for name in paths if not _is_run_owned(name, owned)}
|
|
202
226
|
|
|
203
227
|
|
|
204
228
|
def review_fingerprint(row: Mapping[str, Any], inputs: Mapping[str, Any]) -> str | None:
|
|
@@ -9,7 +9,7 @@ from okstra_ctl.registry.host_registry import default_host_registry
|
|
|
9
9
|
|
|
10
10
|
from .ids import REQUESTABLE_TASK_TYPES
|
|
11
11
|
from .state import WizardError
|
|
12
|
-
from .statefile import load_state_file, save_state_file
|
|
12
|
+
from .statefile import load_state_file, read_state_file, save_state_file
|
|
13
13
|
from .confirmation import confirmation_block
|
|
14
14
|
from .engine import (
|
|
15
15
|
init_state,
|
|
@@ -113,7 +113,7 @@ def main(argv: list[str]) -> int:
|
|
|
113
113
|
return 0
|
|
114
114
|
|
|
115
115
|
if args.cmd == "step":
|
|
116
|
-
state =
|
|
116
|
+
state, restarted = read_state_file(state_path)
|
|
117
117
|
persisted_state = copy.deepcopy(state)
|
|
118
118
|
if args.no_submit and args.answer is not None:
|
|
119
119
|
print(json.dumps(
|
|
@@ -133,6 +133,18 @@ def main(argv: list[str]) -> int:
|
|
|
133
133
|
ensure_ascii=False, indent=2,
|
|
134
134
|
))
|
|
135
135
|
return 2
|
|
136
|
+
if restarted and not args.no_submit:
|
|
137
|
+
save_state_file(state_path, state)
|
|
138
|
+
print(json.dumps({
|
|
139
|
+
"ok": False,
|
|
140
|
+
"error": (
|
|
141
|
+
"the wizard state was saved by an older okstra version and has "
|
|
142
|
+
"restarted from the first step; the answer was not submitted. "
|
|
143
|
+
"Answer the current prompt instead."
|
|
144
|
+
),
|
|
145
|
+
"current": prompt_payload(state, next_prompt(state)),
|
|
146
|
+
}, ensure_ascii=False, indent=2))
|
|
147
|
+
return 0
|
|
136
148
|
try:
|
|
137
149
|
if args.no_submit:
|
|
138
150
|
result = {"echo": "", "next": prompt_payload(state, next_prompt(state))}
|
|
@@ -337,7 +337,10 @@ def _profile_path(workspace_root: Path, task_type: str) -> Path:
|
|
|
337
337
|
raise WizardError(str(exc)) from exc
|
|
338
338
|
|
|
339
339
|
|
|
340
|
-
|
|
340
|
+
# Bump on every change to the saved fields or step ids: a state of the old shape
|
|
341
|
+
# that still loads resumes on a recomputed step, and the answer meant for its
|
|
342
|
+
# saved step lands on another one.
|
|
343
|
+
WIZARD_STATE_VERSION = 3
|
|
341
344
|
|
|
342
345
|
|
|
343
346
|
_V2_STATE_FIELDS = (
|
|
@@ -31,13 +31,18 @@ def _fresh_state_from_stale(payload: dict) -> WizardState:
|
|
|
31
31
|
return WizardState(**kwargs)
|
|
32
32
|
|
|
33
33
|
|
|
34
|
-
def
|
|
34
|
+
def read_state_file(path: Path) -> tuple[WizardState, bool]:
|
|
35
|
+
"""The saved state, and whether it was an older format restarted from scratch."""
|
|
35
36
|
data = load_owned_object(Path(path), artifact="wizard state")
|
|
36
37
|
try:
|
|
37
|
-
return WizardState.from_json(data)
|
|
38
|
+
return WizardState.from_json(data), False
|
|
38
39
|
except StaleWizardStateError:
|
|
39
40
|
# 이전 형식의 진행분은 옮기지 않는다 — 같은 프로젝트로 새 세션을 시작한다.
|
|
40
|
-
return _fresh_state_from_stale(data)
|
|
41
|
+
return _fresh_state_from_stale(data), True
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def load_state_file(path: Path) -> WizardState:
|
|
45
|
+
return read_state_file(path)[0]
|
|
41
46
|
|
|
42
47
|
|
|
43
48
|
def save_state_file(path: Path, state: WizardState) -> None:
|
|
@@ -107,10 +107,16 @@ def _cited_file_paths(content: str) -> set[str]:
|
|
|
107
107
|
# A file that a citation, an evidence note or an Opened list names:
|
|
108
108
|
# `src/a_b.ts:4-9`, **src/a.ts**, [packet](.okstra/x/p.md:3), /abs/src/a.ts.
|
|
109
109
|
# A name counts only with a directory or a line, so prose such as `e.g.` or a
|
|
110
|
-
# version number is not a file.
|
|
110
|
+
# version number is not a file. Bracketed and parenthesised segments are route
|
|
111
|
+
# directories (Next.js `[slug]`, `[[...slug]]`, `(group)`); without them the
|
|
112
|
+
# path was cut at the bracket and a file the worker opened read as unopened.
|
|
113
|
+
_PATH_CHAR = r"(?:[\w.@-]|\[{1,2}[\w.@-]+\]{1,2}|\([\w.@-]+\))"
|
|
111
114
|
_NAMED_FILE_RE = re.compile(
|
|
112
|
-
|
|
113
|
-
|
|
115
|
+
# A match never starts inside a run of path characters — after a segment's
|
|
116
|
+
# closing bracket or at the inner `[` of `[[` either — so a failed scan ends
|
|
117
|
+
# at the run's end once instead of restarting at every bracket.
|
|
118
|
+
rf"(?<![\w./@\])-])(?!(?<=\[)\[)(?P<path>{_PATH_CHAR}*(?:/{_PATH_CHAR}+)*\.[A-Za-z]\w*"
|
|
119
|
+
rf"|(?:{_PATH_CHAR}+/)+(?:Dockerfile|Justfile|Makefile|Procfile|Rakefile))"
|
|
114
120
|
r"(?P<line>:\d+(?:-\d+)?)?"
|
|
115
121
|
)
|
|
116
122
|
|
|
@@ -33,7 +33,8 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
|
|
|
33
33
|
okstra manager task sync --manager-id <manager-id> --task-group <task-group> --task-id <task-id>
|
|
34
34
|
okstra manager task assign --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] [--role <role>] [--tag <tag>] [--assignment <text>]
|
|
35
35
|
okstra manager task note --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --scope <shared|project> [--project-id <project-id>] --body <text>
|
|
36
|
-
okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed]
|
|
36
|
+
okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] [--allow-completed] [--base-ref <ref>] [--manager-session <address>]
|
|
37
|
+
okstra manager task register-session --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --project-id <project-id> [--child-task-id <child-task-id>] --session <address> [--session-name <name>]
|
|
37
38
|
okstra manager task split --manager-id <manager-id> --task-group <task-group> --task-id <task-id> --plan <split-plan.json> [--overwrite]
|
|
38
39
|
okstra manager list managers
|
|
39
40
|
okstra manager list projects --manager-id <manager-id>
|
|
@@ -154,7 +155,12 @@ For launching child work:
|
|
|
154
155
|
|
|
155
156
|
1. Run `okstra manager task sync ...` if the manager snapshot must be refreshed first.
|
|
156
157
|
2. Run `okstra manager task run ...`. It re-reads the child's state from its project, not from the snapshot. When the child is already done there (terminal next phase, or work status `done`), it refuses with the last phase and report path; tell the user that and do not add `--allow-completed` unless the user asks to run the child again.
|
|
157
|
-
|
|
158
|
+
- A child task's first phase branches from a base ref. Pass the one the user chose as `--base-ref <ref>`; the child keeps it for later launches. Without the option, `task run` uses the child's recorded ref, or the ref every sibling of the same project recorded, and `Base ref source` says which (`argument`, `child`, `sibling`). When it is `none` and the child task does not exist in its project yet, ask the user for the base ref and run `task run` again with `--base-ref`; do not pick a branch yourself.
|
|
159
|
+
- When this session can receive messages from other sessions, pass its own address as `--manager-session <address>`. The child context then tells the child lead to message that address with its child task key and its own session address when the run starts, to report again when each phase ends, and to wait for the manager before the next phase. Approval gates stay with the child session's user; the manager recommends, it does not answer them. Use the address the host keeps across restarts, not a display name.
|
|
160
|
+
- A recorded or sibling ref is also passed for a child that already exists. A child whose worktree is registered and checked out ignores it; one whose worktree was released starts its next worktree from it, and one whose registry row is stale with its branch gone is rebuilt from it instead of the recorded commit.
|
|
161
|
+
3. Read the returned fixed fields `Backend`, `Worker dispatch backend`, `Project root`, `Context path`, `Run command`, every numbered `Run arg N`, `Shell command`, `Base ref`, `Base ref source`, and `Manager session`.
|
|
158
162
|
4. Give the user the `Shell command` line verbatim and tell them to run it in a new terminal. It starts the installed launcher in the child project: the launcher fills the task type and brief from the child task manifest or asks for them, prepares the run with the manager context directive, and starts the child lead as a separate host process (`Backend` `spawn-process`).
|
|
159
163
|
|
|
164
|
+
5. When a child lead's first message names its child task key and its session address, record that address with `okstra manager task register-session ... --session <address> [--session-name <name>]`. `task status` then shows each child's `session address` and `session name`; send later directives to that address. Registering the same address and name again records nothing; a new name on the same address replaces the old one, and leaving out `--session-name` keeps the recorded name.
|
|
165
|
+
|
|
160
166
|
Do not run the `Shell command` through this session's Bash tool: it opens an interactive host session. Do not rebuild it from `Run arg N` or swap in `okstra run`, which drops the task inputs and the directive for a lead host.
|
|
@@ -182,6 +182,9 @@ matching section:
|
|
|
182
182
|
standards every run reads; hand-added, checked by `okstra doctor --phase <phase>`.
|
|
183
183
|
- **H. MCP servers** (`mcpServers`) — `okstra mcp add` declares a server,
|
|
184
184
|
`okstra mcp check` shows which provider CLIs reach it.
|
|
185
|
+
- **I. worker defaults** (`workerDefaults`) — saved worker models and counts per
|
|
186
|
+
role, global or per-project. Setup offers this in Step 5; the same flow runs
|
|
187
|
+
whenever the user asks to review or change them later.
|
|
185
188
|
|
|
186
189
|
## Step 4: Verify
|
|
187
190
|
|
|
@@ -189,16 +192,42 @@ matching section:
|
|
|
189
192
|
okstra doctor --runtime <host-runtime>
|
|
190
193
|
```
|
|
191
194
|
|
|
192
|
-
If all checks return `OK`,
|
|
193
|
-
the output and let the user decide whether to re-run install or skip.
|
|
195
|
+
If all checks return `OK`, continue to Step 5. If any check fails, surface
|
|
196
|
+
the output and let the user decide whether to re-run install or skip. A skipped
|
|
197
|
+
failure also skips Step 5, because saving defaults checks each model's
|
|
198
|
+
availability; the hand-off then reports worker defaults as skipped.
|
|
194
199
|
|
|
195
|
-
## Step 5:
|
|
200
|
+
## Step 5: Worker defaults
|
|
201
|
+
|
|
202
|
+
Saved worker defaults let `/okstra-run` fill each configured role's models and
|
|
203
|
+
count without showing its selection screen; roles left unconfigured are still
|
|
204
|
+
asked on every run. Ask once with `prompt_user`:
|
|
205
|
+
|
|
206
|
+
- **Question**: `"Save default worker models and counts now, so okstra-run skips those selection screens?"`
|
|
207
|
+
- **Options**: `Configure now` (recommended) — open the worker settings editor;
|
|
208
|
+
`Skip` — keep choosing on each run; the settings can be opened later with
|
|
209
|
+
"okstra-run worker settings".
|
|
210
|
+
|
|
211
|
+
On `Configure now`, run the worker settings mode of the installed `okstra-run`
|
|
212
|
+
skill with the project root from Step 2 and the project id from Step 3. That
|
|
213
|
+
mode owns the scope choice, role editor, review, save and cancel; it shows any
|
|
214
|
+
values already saved and keeps them unless the user edits them. Do not edit
|
|
215
|
+
`~/.okstra/config.json` or `project.json` by hand, and do not start a task from
|
|
216
|
+
it. When the mode reports that it finished or was cancelled, continue to Step 6
|
|
217
|
+
and carry its final `next.label` text.
|
|
218
|
+
|
|
219
|
+
## Step 6: Hand-off
|
|
196
220
|
|
|
197
221
|
Inform the user with a short summary:
|
|
198
222
|
|
|
199
223
|
> okstra is ready. Runtime: `~/.okstra` (version stamp). Project metadata:
|
|
200
|
-
> `<PROJECT_ROOT>/.okstra/project.json` (`projectId`).
|
|
201
|
-
> `/okstra-run` to start your first task.
|
|
224
|
+
> `<PROJECT_ROOT>/.okstra/project.json` (`projectId`). Worker defaults:
|
|
225
|
+
> `<outcome>`. Run `/okstra-run` to start your first task.
|
|
226
|
+
|
|
227
|
+
Fill `<outcome>` only from what Step 5 observed: the settings mode's final
|
|
228
|
+
`next.label` when it finished, `cancelled, nothing saved` when it was cancelled,
|
|
229
|
+
and `skipped` when the user chose `Skip` or Step 4 skipped Step 5. Do not claim
|
|
230
|
+
that values were saved, changed or absent beyond that text.
|
|
202
231
|
|
|
203
232
|
## Failure modes
|
|
204
233
|
|
|
@@ -335,3 +335,22 @@ existing entries.
|
|
|
335
335
|
prepare repeats the check for the providers a run selects and prints a warning
|
|
336
336
|
for each gap; it never refuses the run. It also warns when the task brief cites
|
|
337
337
|
a Figma URL and no declared server name or alias contains `figma`.
|
|
338
|
+
|
|
339
|
+
## I. Worker defaults (`workerDefaults`)
|
|
340
|
+
|
|
341
|
+
`workerDefaults` saves the worker models for each role, keyed by role name. The
|
|
342
|
+
array fixes both the models and the count; an empty array disables an optional
|
|
343
|
+
role. The project value in `project.json` replaces that role's global value in
|
|
344
|
+
`~/.okstra/config.json`. `/okstra-run` fills each valid configured role without
|
|
345
|
+
showing its selection screen and still asks for roles that are missing or whose
|
|
346
|
+
saved models are unavailable. `modelDefaults` only orders the candidate list and
|
|
347
|
+
never skips a screen.
|
|
348
|
+
|
|
349
|
+
Review, change or clear these values with the same flow as SKILL.md Step 5: run
|
|
350
|
+
the worker settings mode of the installed `okstra-run` skill. It shows the
|
|
351
|
+
current values for every role and saves nothing until the user chooses Save.
|
|
352
|
+
To only read the saved values of both scopes, run:
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
okstra config show --scope all
|
|
356
|
+
```
|