okstra 0.225.1 → 0.227.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 +1 -0
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.mjs +5 -0
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/cli.md +46 -6
- package/docs/project-structure-overview.md +3 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/bin/lib/okstra/cli.sh +5 -1
- package/runtime/bin/lib/okstra/globals.sh +1 -0
- package/runtime/bin/lib/okstra/usage.sh +3 -0
- package/runtime/bin/okstra.sh +2 -0
- package/runtime/prompts/duties/technical-verification-worker.json +2 -1
- package/runtime/prompts/lead/convergence.md +4 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
- package/runtime/prompts/lead/phase-routing.md +7 -3
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +59 -0
- package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +5 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +108 -2
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +206 -0
- package/runtime/python/okstra_ctl/brief_sources.py +200 -0
- package/runtime/python/okstra_ctl/business_flow/store.py +15 -2
- package/runtime/python/okstra_ctl/cmux.py +18 -3
- package/runtime/python/okstra_ctl/code_review_coverage.py +70 -18
- package/runtime/python/okstra_ctl/code_review_target.py +77 -53
- package/runtime/python/okstra_ctl/convergence_critic_prompt.py +4 -1
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +19 -7
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +20 -18
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/implementation_direction.py +10 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +41 -0
- package/runtime/python/okstra_ctl/manager_split.py +185 -27
- package/runtime/python/okstra_ctl/next_phase.py +3 -1
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +128 -0
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +8 -5
- package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +1 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +84 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +13 -5
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/entry.py +67 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/report_assets/implementation-option-selection.template.html +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +127 -18
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +2 -1
- package/runtime/python/okstra_ctl/phases/technical_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/report_assembly.py +23 -2
- package/runtime/python/okstra_ctl/report_views.py +2 -1
- package/runtime/python/okstra_ctl/run.py +61 -2
- package/runtime/python/okstra_ctl/run_context.py +13 -8
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +27 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +29 -0
- package/runtime/python/okstra_ctl/wizard/registry.py +21 -0
- package/runtime/python/okstra_ctl/wizard/render.py +6 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/sources.py +33 -11
- package/runtime/python/okstra_ctl/wizard/state.py +59 -14
- package/runtime/python/okstra_ctl/wizard/steps_options.py +74 -9
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +21 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +11 -4
- package/runtime/python/okstra_ctl/worker_prompt_policy.py +3 -0
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/schemas/final-report-v2.0.schema.json +74 -0
- package/runtime/schemas/final-report-v3.0.schema.json +99 -2
- package/runtime/skills/okstra-brief-gen/SKILL.md +26 -0
- package/runtime/skills/okstra-code-review/SKILL.md +25 -23
- package/runtime/skills/okstra-code-review/references/review-calibration.md +2 -2
- package/runtime/skills/okstra-manager/SKILL.md +15 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- package/runtime/templates/reports/brief.template.md +10 -1
- package/runtime/templates/reports/html/i18n/en.json +8 -0
- package/runtime/templates/reports/html/i18n/ko.json +8 -0
- package/runtime/templates/worker-prompt-preamble.md +1 -1
- package/runtime/validators/validate-brief.py +39 -1
- package/runtime/validators/validate-run.py +5 -0
|
@@ -10014,6 +10014,80 @@
|
|
|
10014
10014
|
"implementation-option-selection",
|
|
10015
10015
|
"implementation-planning"
|
|
10016
10016
|
]
|
|
10017
|
+
},
|
|
10018
|
+
"defectClass": {
|
|
10019
|
+
"$ref": "#/$defs/DefectClass"
|
|
10020
|
+
}
|
|
10021
|
+
}
|
|
10022
|
+
},
|
|
10023
|
+
"DefectClass": {
|
|
10024
|
+
"type": "object",
|
|
10025
|
+
"description": "The defect class a blocker belongs to: the shared mechanism, every location x case cell swept for it, and whether an earlier final-verification run of the same target already blocked on it. Required on every final-verification acceptance blocker by `phases/final_verification/validation.py`.",
|
|
10026
|
+
"required": [
|
|
10027
|
+
"mechanism",
|
|
10028
|
+
"cells",
|
|
10029
|
+
"recurrence"
|
|
10030
|
+
],
|
|
10031
|
+
"additionalProperties": false,
|
|
10032
|
+
"properties": {
|
|
10033
|
+
"mechanism": {
|
|
10034
|
+
"type": "string",
|
|
10035
|
+
"minLength": 1
|
|
10036
|
+
},
|
|
10037
|
+
"cells": {
|
|
10038
|
+
"type": "array",
|
|
10039
|
+
"minItems": 1,
|
|
10040
|
+
"items": {
|
|
10041
|
+
"$ref": "#/$defs/DefectClassCell"
|
|
10042
|
+
}
|
|
10043
|
+
},
|
|
10044
|
+
"recurrence": {
|
|
10045
|
+
"enum": [
|
|
10046
|
+
"new",
|
|
10047
|
+
"recurring"
|
|
10048
|
+
]
|
|
10049
|
+
},
|
|
10050
|
+
"priorBlockers": {
|
|
10051
|
+
"type": "array",
|
|
10052
|
+
"items": {
|
|
10053
|
+
"type": "string",
|
|
10054
|
+
"pattern": "^final-verification-\\d{3,} AB-\\d{3,}$"
|
|
10055
|
+
}
|
|
10056
|
+
}
|
|
10057
|
+
}
|
|
10058
|
+
},
|
|
10059
|
+
"DefectClassCell": {
|
|
10060
|
+
"type": "object",
|
|
10061
|
+
"required": [
|
|
10062
|
+
"location",
|
|
10063
|
+
"case",
|
|
10064
|
+
"verdict",
|
|
10065
|
+
"evidence"
|
|
10066
|
+
],
|
|
10067
|
+
"additionalProperties": false,
|
|
10068
|
+
"properties": {
|
|
10069
|
+
"location": {
|
|
10070
|
+
"type": "string",
|
|
10071
|
+
"minLength": 1
|
|
10072
|
+
},
|
|
10073
|
+
"case": {
|
|
10074
|
+
"type": "string",
|
|
10075
|
+
"minLength": 1
|
|
10076
|
+
},
|
|
10077
|
+
"verdict": {
|
|
10078
|
+
"enum": [
|
|
10079
|
+
"defective",
|
|
10080
|
+
"sound",
|
|
10081
|
+
"unverified",
|
|
10082
|
+
"not-applicable"
|
|
10083
|
+
]
|
|
10084
|
+
},
|
|
10085
|
+
"evidence": {
|
|
10086
|
+
"type": "string",
|
|
10087
|
+
"minLength": 1
|
|
10088
|
+
},
|
|
10089
|
+
"regressionTest": {
|
|
10090
|
+
"type": "string"
|
|
10017
10091
|
}
|
|
10018
10092
|
}
|
|
10019
10093
|
},
|
|
@@ -3510,6 +3510,9 @@
|
|
|
3510
3510
|
"$ref": "#/$defs/ImplementationOptionSafetyBlocker"
|
|
3511
3511
|
}
|
|
3512
3512
|
},
|
|
3513
|
+
"splitAcceptance": {
|
|
3514
|
+
"$ref": "#/$defs/ImplementationOptionSplitAcceptance"
|
|
3515
|
+
},
|
|
3513
3516
|
"unresolvedFeasibilityFacts": {
|
|
3514
3517
|
"type": "array",
|
|
3515
3518
|
"items": {
|
|
@@ -3608,6 +3611,9 @@
|
|
|
3608
3611
|
"$ref": "#/$defs/ImplementationOptionSafetyBlocker"
|
|
3609
3612
|
}
|
|
3610
3613
|
},
|
|
3614
|
+
"splitAcceptance": {
|
|
3615
|
+
"$ref": "#/$defs/ImplementationOptionSplitAcceptance"
|
|
3616
|
+
},
|
|
3611
3617
|
"unresolvedFeasibilityFacts": {
|
|
3612
3618
|
"type": "array",
|
|
3613
3619
|
"items": {
|
|
@@ -3936,6 +3942,18 @@
|
|
|
3936
3942
|
}
|
|
3937
3943
|
}
|
|
3938
3944
|
},
|
|
3945
|
+
"ImplementationOptionSplitAcceptance": {
|
|
3946
|
+
"type": "object",
|
|
3947
|
+
"description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row answered with accept-risk.",
|
|
3948
|
+
"required": ["clarificationRef"],
|
|
3949
|
+
"additionalProperties": false,
|
|
3950
|
+
"properties": {
|
|
3951
|
+
"clarificationRef": {
|
|
3952
|
+
"type": "string",
|
|
3953
|
+
"pattern": "^C-[0-9]{3}$"
|
|
3954
|
+
}
|
|
3955
|
+
}
|
|
3956
|
+
},
|
|
3939
3957
|
"ImplementationOptionUnresolvedFact": {
|
|
3940
3958
|
"type": "object",
|
|
3941
3959
|
"required": [
|
|
@@ -3947,8 +3965,13 @@
|
|
|
3947
3965
|
"properties": {
|
|
3948
3966
|
"resolutionKind": {
|
|
3949
3967
|
"type": "string",
|
|
3950
|
-
"enum": ["user-decision", "technical-verification"],
|
|
3951
|
-
"description": "Optional for historical reads; blocked report publication requires explicit classification."
|
|
3968
|
+
"enum": ["user-decision", "technical-verification", "deferred-gate"],
|
|
3969
|
+
"description": "Optional for historical reads; blocked report publication requires explicit classification. deferred-gate marks a fact only a later gate can close (for example a deployed-environment measurement); it requires gate and does not block candidate validity."
|
|
3970
|
+
},
|
|
3971
|
+
"gate": {
|
|
3972
|
+
"type": "string",
|
|
3973
|
+
"minLength": 1,
|
|
3974
|
+
"description": "For deferred-gate facts: the gate that closes the fact, such as a brief External Gates entry or final-verification user-owned external QA."
|
|
3952
3975
|
},
|
|
3953
3976
|
"clarificationRefs": {
|
|
3954
3977
|
"type": "array",
|
|
@@ -10480,6 +10503,80 @@
|
|
|
10480
10503
|
"implementation-option-selection",
|
|
10481
10504
|
"implementation-planning"
|
|
10482
10505
|
]
|
|
10506
|
+
},
|
|
10507
|
+
"defectClass": {
|
|
10508
|
+
"$ref": "#/$defs/DefectClass"
|
|
10509
|
+
}
|
|
10510
|
+
}
|
|
10511
|
+
},
|
|
10512
|
+
"DefectClass": {
|
|
10513
|
+
"type": "object",
|
|
10514
|
+
"description": "The defect class a blocker belongs to: the shared mechanism, every location x case cell swept for it, and whether an earlier final-verification run of the same target already blocked on it. Required on every final-verification acceptance blocker by `phases/final_verification/validation.py`.",
|
|
10515
|
+
"required": [
|
|
10516
|
+
"mechanism",
|
|
10517
|
+
"cells",
|
|
10518
|
+
"recurrence"
|
|
10519
|
+
],
|
|
10520
|
+
"additionalProperties": false,
|
|
10521
|
+
"properties": {
|
|
10522
|
+
"mechanism": {
|
|
10523
|
+
"type": "string",
|
|
10524
|
+
"minLength": 1
|
|
10525
|
+
},
|
|
10526
|
+
"cells": {
|
|
10527
|
+
"type": "array",
|
|
10528
|
+
"minItems": 1,
|
|
10529
|
+
"items": {
|
|
10530
|
+
"$ref": "#/$defs/DefectClassCell"
|
|
10531
|
+
}
|
|
10532
|
+
},
|
|
10533
|
+
"recurrence": {
|
|
10534
|
+
"enum": [
|
|
10535
|
+
"new",
|
|
10536
|
+
"recurring"
|
|
10537
|
+
]
|
|
10538
|
+
},
|
|
10539
|
+
"priorBlockers": {
|
|
10540
|
+
"type": "array",
|
|
10541
|
+
"items": {
|
|
10542
|
+
"type": "string",
|
|
10543
|
+
"pattern": "^final-verification-\\d{3,} AB-\\d{3,}$"
|
|
10544
|
+
}
|
|
10545
|
+
}
|
|
10546
|
+
}
|
|
10547
|
+
},
|
|
10548
|
+
"DefectClassCell": {
|
|
10549
|
+
"type": "object",
|
|
10550
|
+
"required": [
|
|
10551
|
+
"location",
|
|
10552
|
+
"case",
|
|
10553
|
+
"verdict",
|
|
10554
|
+
"evidence"
|
|
10555
|
+
],
|
|
10556
|
+
"additionalProperties": false,
|
|
10557
|
+
"properties": {
|
|
10558
|
+
"location": {
|
|
10559
|
+
"type": "string",
|
|
10560
|
+
"minLength": 1
|
|
10561
|
+
},
|
|
10562
|
+
"case": {
|
|
10563
|
+
"type": "string",
|
|
10564
|
+
"minLength": 1
|
|
10565
|
+
},
|
|
10566
|
+
"verdict": {
|
|
10567
|
+
"enum": [
|
|
10568
|
+
"defective",
|
|
10569
|
+
"sound",
|
|
10570
|
+
"unverified",
|
|
10571
|
+
"not-applicable"
|
|
10572
|
+
]
|
|
10573
|
+
},
|
|
10574
|
+
"evidence": {
|
|
10575
|
+
"type": "string",
|
|
10576
|
+
"minLength": 1
|
|
10577
|
+
},
|
|
10578
|
+
"regressionTest": {
|
|
10579
|
+
"type": "string"
|
|
10483
10580
|
}
|
|
10484
10581
|
}
|
|
10485
10582
|
},
|
|
@@ -185,6 +185,23 @@ for every variant and every source type below.
|
|
|
185
185
|
missing and where it lives. A bracketed note inside the captured block
|
|
186
186
|
helps the reader, but it does not replace that row: the row is what a later
|
|
187
187
|
phase sees when it asks whether the source arrived complete.
|
|
188
|
+
4. **Every local document the brief is derived from is its own Source.** A
|
|
189
|
+
spec, plan or note under the project root that you read while drafting —
|
|
190
|
+
one the reporter named, or one you opened because a ticket or the
|
|
191
|
+
conversation pointed at it — gets its own `### Source N — file` entry,
|
|
192
|
+
not only a mention in Context. When git does not track the file (a
|
|
193
|
+
`.project-docs/` spec, for example), write the entry with
|
|
194
|
+
`- format: by-reference`, a project-relative `ref`, and an empty fence:
|
|
195
|
+
the task worktree is a checkout without that file, and prepare copies it
|
|
196
|
+
read-only into the analysis packet's `## Cited Local Documents` on every
|
|
197
|
+
run, so later revisions of the document reach the next phase. A tracked
|
|
198
|
+
file is in the worktree; capture it as-is per rule 1.
|
|
199
|
+
|
|
200
|
+
**Enforced:** `validators/validate-brief.py`
|
|
201
|
+
(`check_cited_local_documents`) refuses a brief that names a git-untracked
|
|
202
|
+
document under the project root outside `## Source Material` without such
|
|
203
|
+
an entry. `okstra brief-sources attach --project-root <PROJECT_ROOT>
|
|
204
|
+
--brief <path>` appends the missing entries by reference.
|
|
188
205
|
|
|
189
206
|
### 1.0. brief variant
|
|
190
207
|
|
|
@@ -235,6 +252,9 @@ each source's raw content **separately** under the `Source Material
|
|
|
235
252
|
Take an absolute or project-relative path via free-text. Read the entire
|
|
236
253
|
file. Re-ask if it doesn't exist. Captured content is preserved **verbatim**
|
|
237
254
|
in Source Material.
|
|
255
|
+
When the file is under the project root and git does not track it, record
|
|
256
|
+
it by reference instead (capture contract rule 4): the entry's `ref` is the
|
|
257
|
+
project-relative path, `format: by-reference`, and the fence stays empty.
|
|
238
258
|
|
|
239
259
|
### 1b. `Issue tracker ticket`
|
|
240
260
|
|
|
@@ -1047,6 +1067,12 @@ Lenses` rules.
|
|
|
1047
1067
|
2. If it exits non-zero, **fix the offending brief(s) and re-run**. Do NOT
|
|
1048
1068
|
print the Step 7 message until the validator passes.
|
|
1049
1069
|
|
|
1070
|
+
A `local document ... has no ### Source N — file entry` failure is fixed
|
|
1071
|
+
by `okstra brief-sources attach --project-root <PROJECT_ROOT> --brief
|
|
1072
|
+
<path>`, which appends the entry and changes no other line. For a brief
|
|
1073
|
+
other than the one you just wrote, show the user the listed path and ask
|
|
1074
|
+
before running it.
|
|
1075
|
+
|
|
1050
1076
|
3. If neither validator copy is present, fall back to a manual checklist:
|
|
1051
1077
|
confirm each brief has all ten required frontmatter keys (`type`,
|
|
1052
1078
|
`brief-id`, `parent-id`, `ticket-id`, `source-type`, `task-group`,
|
|
@@ -6,7 +6,7 @@ description: >-
|
|
|
6
6
|
unrelated to an okstra run. The tell is a review request over a diff:
|
|
7
7
|
"review this stage", "review my branch", "code review", "leave the review
|
|
8
8
|
in a file". The orchestrator censuses the diff into an explicit worklist,
|
|
9
|
-
one
|
|
9
|
+
one to three reviewers (the user picks) each return a verdict for every cell
|
|
10
10
|
against this project's coding-preflight rules, a coverage audit
|
|
11
11
|
re-dispatches any gap, and the orchestrator settles what the reviewers
|
|
12
12
|
disagree on. NOT for writing a PR body (okstra-pr-gen), starting a run
|
|
@@ -75,13 +75,14 @@ Pick the mode from what the user actually gave you:
|
|
|
75
75
|
**Branch mode.**
|
|
76
76
|
|
|
77
77
|
1. If the user named no branch, list `git -C <projectRoot> branch --format='%(refname:short)'` and offer a 3-option picker with the current branch as the first recommendation.
|
|
78
|
-
2.
|
|
78
|
+
2. Ask for the comparison base branch, tag or commit unless the user already named one. Do not infer a parent branch or substitute the repository default. Pass it as `--base <ref>`; branch mode rejects an omitted or invalid base and freezes the selected ref as a commit.
|
|
79
|
+
3. Detached HEAD — `git -C <projectRoot> symbolic-ref --quiet HEAD` prints nothing — is refused: ask the user to name a branch. Do not review a bare commit.
|
|
79
80
|
|
|
80
81
|
**Then call the target CLI.** One call resolves everything the rest of this skill needs; the only reason to call it again is a base the user overrides in the confirmation step below.
|
|
81
82
|
|
|
82
83
|
```bash
|
|
83
84
|
okstra code-review target --task-key <taskKey> --stage <N> --project-root <projectRoot> --text
|
|
84
|
-
okstra code-review target --branch <name>
|
|
85
|
+
okstra code-review target --branch <name> --base <ref> --project-root <projectRoot> --text
|
|
85
86
|
```
|
|
86
87
|
|
|
87
88
|
`Status: ready` carries `Project root`, `Mode`, `Worktree path`, `Branch`, `Base commit`, `Head commit`, `Review path`, `Round`, and `Report language`; stage mode adds `Task key`, `Task root`, and `Stage`. Carry every field verbatim into the later steps — none of them is recomputed anywhere below.
|
|
@@ -98,10 +99,9 @@ okstra model-io code-review-input --project-root <projectRoot> --base <baseCommi
|
|
|
98
99
|
Carry this fixed Markdown view into the census and reviewer prompts. Do not
|
|
99
100
|
pass task manifests, target-CLI JSON, or arbitrary JSON fields to a reviewer.
|
|
100
101
|
|
|
101
|
-
**
|
|
102
|
-
|
|
103
|
-
**Where to run git.** Use `worktreePath` when it is non-empty; otherwise run git in `projectRoot` and read the stage's `branch` ref. An empty `worktreePath` does **not** mean the stage is gone: a completed stage's registry row is `released`, so the field is empty even when the directory is still on disk. Either way the commits are on the branch. With no worktree there is no checked-out tree to read whole files from, so every brief tells the reviewer to read a file at the reviewed commit with `git -C <projectRoot> show <headCommit>:<path>` — never from the project root's working tree, which holds a different commit.
|
|
102
|
+
**The user owns the comparison base.** Branch mode requires their selected base branch or commit and resolves it to a fixed `baseCommit`. Stage mode keeps the recorded stage base unless the user explicitly overrides it; a recorded or overridden stage value may still be a ref, so carry it verbatim. Do not substitute the default branch or an inferred parent.
|
|
104
103
|
|
|
104
|
+
**Read the frozen head in both modes.** Run git in `worktreePath` when it is non-empty, otherwise in `projectRoot`; call that location `<gitRoot>`. Read every whole source file, caller and test with `git -C <gitRoot> show <headCommit>:<path>`, including clean observations. A checkout on the selected branch may contain uncommitted edits or move during review. `worktreePath` identifies a Git repository, not authority to read its working files. Branch targets leave it empty; a released stage can also have an empty path.
|
|
105
105
|
**Then show the base and confirm it — branch mode and stage mode alike.** The CLI's answer is a recommendation the user has not seen yet, and a base nobody looked at is how unrelated commits slip into a review unnoticed. Print `baseCommit` verbatim next to `git -C <workdir> log -1 --oneline <baseCommit>` so the commit it names is legible, then ask with a 3-option picker:
|
|
106
106
|
|
|
107
107
|
1. `Use <baseCommit>` — **the recommendation**, the value the CLI returned.
|
|
@@ -124,16 +124,18 @@ A large census is never truncated. Report the cell count and confirm before disp
|
|
|
124
124
|
|
|
125
125
|
## Step 3 — Materialize and dispatch the reviewers in parallel
|
|
126
126
|
|
|
127
|
-
**Ask how many reviewers** with
|
|
127
|
+
**Ask how many reviewers** with these choices:
|
|
128
|
+
|
|
129
|
+
1. `2 reviewers` — **the recommendation**: two different models each review the whole census.
|
|
130
|
+
2. `3 reviewers` — three different models each review the whole census; higher execution cost.
|
|
131
|
+
3. `1 reviewer` — cheaper; you adjudicate every finding it returns.
|
|
128
132
|
|
|
129
|
-
1
|
|
130
|
-
2. `1 reviewer` — cheaper; you adjudicate every finding it returns.
|
|
131
|
-
3. `Enter directly` — always last; accept only `1` or `2`.
|
|
133
|
+
Accept only `1`, `2` or `3`; a host may also allow direct text input.
|
|
132
134
|
|
|
133
135
|
Then ask the runtime what those reviewers run — do not choose the role or the providers here:
|
|
134
136
|
|
|
135
137
|
```
|
|
136
|
-
okstra agent-prompt resolve-operation --operation code-review --count <1|2>
|
|
138
|
+
okstra agent-prompt resolve-operation --operation code-review --count <1|2|3>
|
|
137
139
|
```
|
|
138
140
|
|
|
139
141
|
It prints the duty, the role, the reviewer count, and one `slot` line per reviewer carrying that slot's
|
|
@@ -154,9 +156,9 @@ process, run the provider wrapper `~/.okstra/bin/okstra-<provider>-exec.sh <proj
|
|
|
154
156
|
with the verified prompt path (`okstra worker-dispatch` dispatches only a run manifest's assignments, not a
|
|
155
157
|
standalone prompt). The wrapper records the provider's output in the prompt path with `.md` replaced by
|
|
156
158
|
`.log`. Never substitute one model value for the other. Dispatch the verified calls in parallel when the host supports
|
|
157
|
-
it. **Every reviewer receives the same brief**
|
|
159
|
+
it. **Every reviewer receives the same brief** and reviews every cell independently. Every brief carries:
|
|
158
160
|
|
|
159
|
-
- the diff
|
|
161
|
+
- the diff and the fixed-head read command `git -C <gitRoot> show <headCommit>:<path>`, where Step 1 resolved `<gitRoot>`
|
|
160
162
|
- the project layout in one or two lines (where source, tests, and — if the routing found one — domain / ports / adapters live)
|
|
161
163
|
- **the whole census** — the shared rule catalog once and every grouped cell of all four axes, verbatim
|
|
162
164
|
- the absolute paths of every applied pack (from step 2's routing)
|
|
@@ -188,10 +190,10 @@ Keep normal output to one compact Coverage Verdicts row per cell, with explicit
|
|
|
188
190
|
For each reviewer separately, audit its grouped rows and explicit rule-ID accounting using its verified completion marker:
|
|
189
191
|
|
|
190
192
|
```bash
|
|
191
|
-
okstra code-review check-coverage --project-root <projectRoot> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
|
|
193
|
+
okstra code-review check-coverage --project-root <projectRoot> --head <headCommit> --census <grouped-census-path> --completion <completion-path> [--completion <gap-fill-completion-path> ...]
|
|
192
194
|
```
|
|
193
195
|
|
|
194
|
-
The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
|
|
196
|
+
Pass the `headCommit` that `okstra code-review target` returned. The command reads each evidence file as `<headCommit>` holds it (`git show <headCommit>:<path>`), never the project root's working tree, so a review run from a checkout on another commit audits the reviewed lines. The command reuses the existing completion verification boundary and refuses mixed model assignments. Exit 0 means every cell accounts for all rules in its group with valid source evidence and no unknown cell ID; exit 1 lists missing cells, missing rule IDs or invalid grouped verdicts; exit 2 reports invalid input or completion evidence. It validates the shared catalog and source anchors, but does not establish whether the selected references are exhaustive or a verdict is true.
|
|
195
197
|
|
|
196
198
|
For missing checks, dispatch one gap-fill invocation per reviewer on that reviewer's original slot, carrying only its incomplete grouped cells, their shared catalog entries, the same range and rule paths. Ask for one complete row for each such cell, not separate replies per missing rule. Use a new invocation ID and repeat the full materialize → verify → dispatch → materialize-result → complete → verify-completion boundary. Re-run the audit with that reviewer's initial and gap-fill markers. Earlier usable verdicts remain unchanged. An invocation with unknown IDs is invalid; record its rejection and request a corrected new invocation before auditing the retained valid completions. Do not silently relabel IDs.
|
|
197
199
|
|
|
@@ -207,17 +209,17 @@ Reviewers miscount lines. Pass every finding's `path:line` to one call:
|
|
|
207
209
|
okstra code-review check-lines --project-root <projectRoot> --base <baseCommit> --head <headCommit> --cite <path:line> [--cite <path:line> ...]
|
|
208
210
|
```
|
|
209
211
|
|
|
210
|
-
`ok` keeps the citation. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
|
|
212
|
+
`ok` keeps the citation. A fully deleted file has no head-side citation; a deletion within a surviving file retains its anchor before the cut. For `not-changed` or `not-in-diff`, find the finding's `snippet` in `git -C <projectRoot> show <headCommit>:<path>`; if it sits on one of the changed lines the output lists, replace the line number with that line and say so in the finding. A finding whose snippet is on no changed line goes to `Rejected` as "cites no changed line". Re-run `check-lines` until every kept citation is `ok`.
|
|
211
213
|
|
|
212
214
|
## Step 3.7 — Settle the findings
|
|
213
215
|
|
|
214
216
|
Reviewers are wrong in a way a census cannot catch: a claim about code they did not open. What you settle depends on the reviewer count. Before pairing findings, check every finding, including agreed ones, against its `kind`: an `execution-error` needs an evidenced reachable `failure`; a `design-violation` needs an applicable named rule, code evidence, and concrete `impact`. Both need a fix. Missing or unsupported required evidence goes to `Rejected` with the specific reason; do not demand a runtime failure for a design violation.
|
|
215
217
|
|
|
216
|
-
**Two reviewers.**
|
|
218
|
+
**Two or three reviewers.** Group findings by the same `path:line` and defect. Inspect every reported finding, including one supported by only one of three reviewers; silence or a clean verdict is not a vote against it. Then:
|
|
217
219
|
|
|
218
|
-
- **Agreed** —
|
|
219
|
-
- **Graded differently** —
|
|
220
|
-
- **One-sided** —
|
|
220
|
+
- **Agreed** — every reviewer reports it with the same severity and timing. It keeps its severity and timing after the evidence and kind checks above; agreement does not replace those checks.
|
|
221
|
+
- **Graded differently** — at least two report it with different severity or timing. Choose one reporting reviewer's severity/timing pair for that finding after reading the code, and record all reported values and your reason. Never choose an unreported value or use majority vote in place of evidence.
|
|
222
|
+
- **One-sided** — fewer than all reviewers report it with no grading disagreement; the others returned `clean` for that cell or reported something else. Adjudicate it as below.
|
|
221
223
|
|
|
222
224
|
**One reviewer.** Adjudicate every finding it returns.
|
|
223
225
|
|
|
@@ -226,13 +228,13 @@ Reviewers are wrong in a way a census cannot catch: a claim about code they did
|
|
|
226
228
|
- **Confirmed** — the code supports the execution failure or the applicable design violation and its impact. The finding keeps its severity and timing.
|
|
227
229
|
- **Rejected** — the code contradicts the claim (the called function never reads `this`, the value cannot be null there, the branch is unreachable). Move it to `Rejected` with the contradicting `path:line` and one sentence on what it shows.
|
|
228
230
|
|
|
229
|
-
Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing
|
|
231
|
+
Rejecting is a statement about the code, so it always carries a `path:line`. Never reject for being unconvinced. Apart from choosing among the reporting reviewers' values, never promote, demote, or re-time a finding. Confirmed and agreed `park` findings go to `Parked`, unscored.
|
|
230
232
|
|
|
231
233
|
## Step 4 — Merge and write
|
|
232
234
|
|
|
233
235
|
1. **Read `references/review-calibration.md`** (next to this file) and follow its report section — you are the one writing the file, and it fixes the Coverage sentence, the per-finding line format, the Score table columns, and the total row. The reviewers were given it for their verdicts; the report obeys it too.
|
|
234
|
-
2. **Dedupe across axes and reviewers.** The same defect surfaced by
|
|
235
|
-
3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing
|
|
236
|
+
2. **Dedupe across axes and reviewers.** The same defect surfaced by multiple axes or reviewers stays once, under the rule that explains it best, and each finding says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`.
|
|
237
|
+
3. **Severity is the reviewers'; truth is yours.** The merge never re-grades or re-times a finding except by choosing among reporting reviewers' values in Step 3.7.
|
|
236
238
|
4. **Write the report to `reviewPath`** with the Write tool (it creates the parent directories). Frontmatter fields, in this order:
|
|
237
239
|
|
|
238
240
|
```yaml
|
|
@@ -122,8 +122,8 @@ Merged and adjudicated by the orchestrator, written to `reviewPath`. Sections, i
|
|
|
122
122
|
- **Parked** — `park` findings, with their severity, not scored.
|
|
123
123
|
- **Rejected** — findings the orchestrator's adjudication disproved or that cite no changed line: the reviewer's claim in one line, then the contradicting `path:line` and what it shows. Not scored.
|
|
124
124
|
|
|
125
|
-
- **Coverage** — two or three lines: the reviewers (`provider/model`, one
|
|
126
|
-
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with
|
|
125
|
+
- **Coverage** — two or three lines: the reviewers (`provider/model`, one to three); N changed files → S `structural` / F `semantic` / T `state-and-tests` / G `general` cells, all verdicted by every reviewer; M files excluded with reasons; the applied packs, and any pack that was unavailable; and how the findings were settled — agreed, graded by the orchestrator, confirmed by the orchestrator, rejected. The four cell counts are at the census's granularity — one cell per target per axis. Also show grouped cells expected and covered per reviewer, list any missing rule IDs and count reasoned applicability exclusions. Never present the number of rule flags as the number of independent review targets.
|
|
126
|
+
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator` (with every reporting reviewer's values), or `confirmed by orchestrator`.
|
|
127
127
|
- **Score** — every confirmed `now` finding gets a row, and the table is emitted even when there are none, with a single total row reading 0:
|
|
128
128
|
|
|
129
129
|
```
|
|
@@ -69,9 +69,11 @@ Use this when one Linear project, or one parent issue, covers work in several re
|
|
|
69
69
|
3. For each issue, propose target projects from evidence: labels, team, repository names or paths in the body. Confirm with `prompt_user` (multi-select, recommended projects first, reason in each description).
|
|
70
70
|
4. For each (issue, project) pair, draft the scope: the part of the issue this project implements. Confirm it with `prompt_user` offering one or two drafts plus a custom-input option. A pair without scope is rejected by the CLI.
|
|
71
71
|
5. Author each pair's brief fields under the okstra-brief-gen brief contract: bodies verbatim, `EB-NNN` / `PB-NNN` / `EO-NNN` items as `<id> <observable condition> — verify: <how>`, anything without an observation method under `externalGates`, and `openQuestions` rows prefixed `general:`, `terminology:`, `intent-check:`, `conversion-block:` or `adr-candidate:`.
|
|
72
|
+
List in `localSources` every local document under that project's root you read to author the pair (a spec, a plan, a note), as a path relative to the project root. Each becomes a `### Source N — file` entry with `format: by-reference`, so every run of the child copies the current file into its analysis packet; a task worktree is a checkout and lacks an untracked `.project-docs/` file. A path outside the project root or a missing file rejects the plan, and a brief whose text names an untracked document that `localSources` does not list fails `validate-brief`.
|
|
72
73
|
6. Write the plan JSON below with the Write tool to a scratch path outside the project roots, then run `okstra manager task split ... --plan <path>`.
|
|
73
74
|
- `split plan rejected` or `rendered briefs failed validate-brief`: fix the named fields and run it again. Nothing was written.
|
|
74
|
-
-
|
|
75
|
+
- To add issues or projects to an earlier split, add them to the kept `split-plan.json` content and run the split again without `--overwrite`. Each brief's status is `created`, `unchanged`, `refreshed` or `overwritten`. The CLI renders each existing brief from the kept plan and from the new plan, both with the brief's original `created` date. When the two differ only in `### Out of scope`, `## Related Artifacts` and `## Related Task Graph`, it removes and appends just the changed lines in those sections (`refreshed`) and keeps every other line, hand edits included. An edit to the pair's own `outOfScope` list is applied the same way. A brief the new plan does not change stays `unchanged`, even with hand edits.
|
|
76
|
+
- `briefs already exist with content this plan would change`: the plan changes a listed brief outside those sections, for example its own scope or Context. Show the listed paths and ask before adding `--overwrite`, which re-renders only those briefs and replaces their hand edits. A brief with no kept plan to compare against is also listed when its text differs.
|
|
75
77
|
7. Each `Brief N task key` is `<project-id>:<task-group>:<child-task-id>`. Start one with `okstra manager task run ... --project-id <project-id> --child-task-id <child-task-id>` and follow the Child Launch Rule. The packet already carries `--task-brief`, and `--task-type` until the child task exists.
|
|
76
78
|
|
|
77
79
|
Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommendedPhase` is `requirements-discovery` (default), `error-analysis` or `improvement-discovery`; `relations[].relation` uses the brief Related Task Graph values; list fields may be omitted.
|
|
@@ -90,7 +92,8 @@ Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommend
|
|
|
90
92
|
"recommendedPhase": "requirements-discovery",
|
|
91
93
|
"context": "<text>", "problem": "<text>", "desiredOutcome": "<text>",
|
|
92
94
|
"expectedBehavior": [], "preservedBehavior": [], "expectedOutcome": [],
|
|
93
|
-
"externalGates": [], "constraints": [], "openQuestions": []
|
|
95
|
+
"externalGates": [], "constraints": [], "openQuestions": [],
|
|
96
|
+
"localSources": [".project-docs/specs/<spec>.md"]
|
|
94
97
|
}
|
|
95
98
|
]
|
|
96
99
|
}
|
|
@@ -100,6 +103,16 @@ Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommend
|
|
|
100
103
|
|
|
101
104
|
The CLI writes each brief to `<projectRoot>/.okstra/briefs/<group-slug>/<ticketId>-<file-title>.md` (`<group-slug>` is the task group lowercased, with each run of characters other than `a-z` and `0-9` replaced by `-`, so `Upload V2` becomes `upload-v2`) with a `## Project Scope` section: this project's scope, `outOfScope`, and the scope of every other project the same issue went to. It validates every brief with the brief validator before writing any file, registers the child tasks, and keeps the plan at `split-plan.json` in the manager task directory.
|
|
102
105
|
|
|
106
|
+
## Upgrading an Existing Brief
|
|
107
|
+
|
|
108
|
+
A brief written before `localSources` existed may name a local document only in Context; `validate-brief` and every prepare of that child then refuse it. Do not hand-edit the brief and do not re-split to fix it: `--overwrite` re-renders the brief and replaces later edits. Run
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
okstra brief-sources attach --project-root <project-root> --brief <brief-path>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
It appends one `### Source N — file` entry (`format: by-reference`) per cited untracked document at the end of Source Material and changes no other line, so `EB-` / `PB-` / `EO-` ids, External Gates and later edits stay. Show the user the printed paths. Add the same paths to the pair's `localSources` in the kept `split-plan.json` before any later re-split, so the re-rendered brief carries them.
|
|
115
|
+
|
|
103
116
|
## Overview Page
|
|
104
117
|
|
|
105
118
|
When the user wants to see a manager at a glance, run `okstra manager task sync ...` for each task listed by `okstra manager list tasks ...` whose snapshot must be current, then run `okstra manager view --manager-id <manager-id>` and give the user the returned `View URL`. The page reads manager files only, so each task shows the state of its last sync and prints its own sync command.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: okstra-run
|
|
3
|
-
description: Use when the user wants to start or continue an okstra cross-verification task
|
|
3
|
+
description: Use when the user wants to start or continue an okstra cross-verification task in this session, or configure its saved worker roles, models, and counts. Includes "okstra run", "run the next phase", and "okstra-run worker settings".
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# OKSTRA Run (in-session)
|
|
@@ -17,6 +17,25 @@ Launch an okstra task — gather inputs interactively via the **wizard state mac
|
|
|
17
17
|
|
|
18
18
|
- The user is inside a supported agent host and asks to start an okstra task ("run okstra here", "start an error-analysis on this branch", "okstra implementation-planning for INV-1234").
|
|
19
19
|
- Continue an existing task (next phase) without leaving the current agent session.
|
|
20
|
+
- Configure global worker defaults or project overrides without starting a task.
|
|
21
|
+
|
|
22
|
+
## Worker settings mode
|
|
23
|
+
|
|
24
|
+
When the user asks to configure saved worker roles, models, or counts, enter settings mode before the task-launch preflight. The wizard owns the scope, role editor, review, save, and cancel flow. Use `okstra wizard` rather than editing the configuration files directly.
|
|
25
|
+
|
|
26
|
+
Use the host identity and live semantic-function declaration from Step 1. Settings do not start a lead or require a configured project. To discover the current project's registration, use `okstra config show --scope project --cwd <absolute-current-directory>`; when its project entry is unavailable, omit both project flags below. Do not start `/okstra-setup` for a global settings request.
|
|
27
|
+
|
|
28
|
+
Get a state path with `okstra wizard new-state-file`, then initialize with literal values:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
okstra wizard init --worker-settings --state-file /absolute/state.json --host-runtime <host-runtime> --available-function plain_text_input
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
For a registered project, also pass its `--project-root` and `--project-id`. The response includes the absolute `relayContract` path and `runtime`. Read that contract and compute the allowed live-function intersection using Step 1's relay rules. If the intersection includes additional functions, initialize the same still-unanswered settings state once more with those `--available-function` flags. Settings initialization does not write configuration.
|
|
35
|
+
|
|
36
|
+
Relay `next` through the existing prompt loop and submit with `okstra wizard step --state-file <literal-path> --answer <literal-answer>`. The wizard shows all role summaries together and lets the user edit only the roles they choose. Project inheritance, explicit zero workers, and save validation belong to the wizard. Changes remain drafts until the user chooses Save on its review screen.
|
|
37
|
+
|
|
38
|
+
For settings, `kind: done` means the settings transaction finished: show `next.label` and stop. `kind: aborted` means no settings were saved. Do not continue to launch Step 5, `outcome`, `render-args`, or `render-bundle` in either case. Resume ordinary task launching only on a separate user request.
|
|
20
39
|
|
|
21
40
|
## When NOT to Use
|
|
22
41
|
|
|
@@ -208,6 +227,7 @@ Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How
|
|
|
208
227
|
That is the entire interactive flow. The wizard handles:
|
|
209
228
|
|
|
210
229
|
- project report language before task selection: when `.okstra/project.json` has no `reportLanguage` value, ask for a language tag and save the answer to that file. An existing value skips this question. Prompt rendering and progress estimation do not save a language,
|
|
230
|
+
- saved worker rosters: `workerDefaults` in the project configuration replaces that role's global array in `~/.okstra/config.json`. The array fixes both models and count; an empty array explicitly disables an optional role. Valid configured roles skip their selection screens without a separate defaults question. Missing or unavailable roles alone are asked. The confirmation shows the count, models, source, and disabled roles; Edit changes only this run. Explicit inputs and an explicitly reused previous roster take precedence. `modelDefaults` remains a candidate-order preference and does not skip screens. Dynamic verifiers retain their source assignments,
|
|
211
231
|
- new-vs-existing task split (remaining work — `workStatus != done` — top-3 newest recommendations + Enter directly), task-group / task-id slug validation (task-group offers the top-3 newest candidates combining recent task use + recent `.okstra/briefs/<group>/` creation activity + Enter directly; task-id offers the top-3 recent candidates from the same group + Enter directly),
|
|
212
232
|
- task-type pick (3 options + Enter directly; Enter directly is validated against the full task-type whitelist in a follow-up `text` step). **For a brand-new task the brief is asked first** and the three options are entry phases only (`requirements-discovery` / `improvement-discovery` / `project-analysis` / `feature-analysis` / `change-impact-analysis` / `error-analysis`) — a new task-key has no approved plan, no implementation and no commits, so `implementation`, `final-verification` and `release-handoff` cannot be entered there; the recommended slot comes from the selected brief's `Recommended next phase:` line and falls back to `requirements-discovery` when the brief carries none. For an existing task-key what fills those three depends on `workflow.nextRecommendedPhase` — an object `{phase, status, rationale}`, not a phase-name string. `status: ready` gives the classic trio: its `phase` marked recommended, re-run the current phase, the lifecycle's next step. Any other status contributes nothing at all, since both the recommended slot and the next-step slot derive from that phase — re-run the current phase becomes the first option and the remaining slots fill unlabelled from recently used task-types and then the whitelist. Never recover a phase name from a non-`ready` pointer and propose it yourself: prepare deliberately lowers the pointer to `pending` while its run is unfinished, and the missing recommendation is that signal,
|
|
213
233
|
- brief path — **for a new task it is asked right after task-group, before the task-type** (it is the only input that says what the task is, and the task-type recommendation reads it); for an existing task it is **asked only for entry task-types (requirements-discovery / error-analysis / improvement-discovery / project-analysis / feature-analysis / change-impact-analysis)** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, sorted by the newer of file-created/modified time and latest task-catalog use; direct input last; `Keep / Change` for existing entry tasks). `project-analysis`, `feature-analysis`, and `change-impact-analysis` are brief entry task types. On an existing task a downstream lifecycle task-type auto carries in the manifest's brief, and when no registered brief exists a `brief_carry` 3-option prompt appears (recommend switching to entry / Enter directly / Abort). `release-handoff` has no brief step of its own — a new-task run answers the brief before the type is known, and the brief is dropped at render time, so prepare always generates the input document that cites the verification report,
|
|
@@ -43,6 +43,15 @@ attachment returned as a link, an opaque embed node) gets a
|
|
|
43
43
|
`conversion-block:` row in Open Questions naming what is missing. Heading was
|
|
44
44
|
originally "Source Material (verbatim — do not modify)" — the parenthetical
|
|
45
45
|
is a reviewer note, not body text.
|
|
46
|
+
`format: by-reference` applies only to a `file` source whose `ref` is a path
|
|
47
|
+
under the project root (absolute, or relative to the project root): leave
|
|
48
|
+
the fence empty, and prepare copies the file read-only into the analysis
|
|
49
|
+
packet's `## Cited Local Documents` on every run. Use it for an untracked
|
|
50
|
+
local document such as a `.project-docs/` spec, which the task worktree does
|
|
51
|
+
not contain. A file only mentioned in Context is not read, and
|
|
52
|
+
`validators/validate-brief.py` refuses a brief that names an untracked
|
|
53
|
+
document outside Source Material without its own `file` entry;
|
|
54
|
+
`okstra brief-sources attach` appends the missing entries.
|
|
46
55
|
-->
|
|
47
56
|
|
|
48
57
|
### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
|
|
@@ -50,7 +59,7 @@ is a reviewer note, not body text.
|
|
|
50
59
|
- ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
|
|
51
60
|
- fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
|
|
52
61
|
- fetched-at: <YYYY-MM-DD HH:MM>
|
|
53
|
-
- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
|
|
62
|
+
- format: <as-is | by-reference | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
|
|
54
63
|
|
|
55
64
|
```
|
|
56
65
|
<Paste the raw source here without changing a single character.>
|
|
@@ -451,6 +451,12 @@
|
|
|
451
451
|
"what-blocks-acceptance": "What blocks acceptance",
|
|
452
452
|
"nothing-is-holding-acceptance": "Nothing is holding acceptance.",
|
|
453
453
|
"follow-up": "Follow-up:",
|
|
454
|
+
"defect-mechanism": "Mechanism:",
|
|
455
|
+
"recurring-class": "Recurring — an earlier run blocked on this class:",
|
|
456
|
+
"location": "Location",
|
|
457
|
+
"case": "Case",
|
|
458
|
+
"verdict": "Verdict",
|
|
459
|
+
"regression-test": "Regression test",
|
|
454
460
|
"residual-risk": "Residual risk",
|
|
455
461
|
"owner": "Owner:",
|
|
456
462
|
"escalation-condition": "Escalation condition:",
|
|
@@ -521,6 +527,8 @@
|
|
|
521
527
|
"safety-blockers": "Safety blockers",
|
|
522
528
|
"technical-verification": "Technical verification pending",
|
|
523
529
|
"user-decision": "User decision record",
|
|
530
|
+
"deferred-gate": "Closes at a later gate",
|
|
531
|
+
"split-acceptance": "Split vote accepted as a risk by the user",
|
|
524
532
|
"classification-required": "Classification required before reassembly",
|
|
525
533
|
"unresolved-facts": "Unresolved feasibility facts",
|
|
526
534
|
"expected-outcome": "Expected outcome",
|
|
@@ -451,6 +451,12 @@
|
|
|
451
451
|
"what-blocks-acceptance": "수용을 막는 것",
|
|
452
452
|
"nothing-is-holding-acceptance": "수용을 막는 것이 없습니다.",
|
|
453
453
|
"follow-up": "후속:",
|
|
454
|
+
"defect-mechanism": "원리:",
|
|
455
|
+
"recurring-class": "재발 — 이전 run 이 이 계열로 막혔음:",
|
|
456
|
+
"location": "위치",
|
|
457
|
+
"case": "경우",
|
|
458
|
+
"verdict": "판정",
|
|
459
|
+
"regression-test": "회귀 테스트",
|
|
454
460
|
"residual-risk": "남은 위험",
|
|
455
461
|
"owner": "담당:",
|
|
456
462
|
"escalation-condition": "에스컬레이션 조건:",
|
|
@@ -521,6 +527,8 @@
|
|
|
521
527
|
"safety-blockers": "안전 차단 요인",
|
|
522
528
|
"technical-verification": "기술 검증 대기",
|
|
523
529
|
"user-decision": "사용자 결정 기록",
|
|
530
|
+
"deferred-gate": "이후 게이트에서 확인",
|
|
531
|
+
"split-acceptance": "갈린 표를 사용자가 위험 감수로 수용",
|
|
524
532
|
"classification-required": "재조립 전 해결 방식 분류 필요",
|
|
525
533
|
"unresolved-facts": "미확정 실행 가능성 사실",
|
|
526
534
|
"expected-outcome": "예상 결과",
|
|
@@ -10,7 +10,7 @@ Read `analysis-packet.md`, the primary compact input, end-to-end. Source files n
|
|
|
10
10
|
|
|
11
11
|
### Reading rules
|
|
12
12
|
|
|
13
|
-
- Read every file enumerated under `[Required reading]` or `## Inputs` completely.
|
|
13
|
+
- Read every file enumerated under `[Required reading]` or `## Inputs` completely, in pages of at most 200 lines (`sed -n '<start>,<end>p'`). A whole-file `cat` or view of a long file is cut without notice. Cover every line and record the page boundaries.
|
|
14
14
|
- Write Reading Confirmation to `**Audit sidecar path:**`, never to the main worker-results file. A `## 0. Reading Confirmation` heading in the main result is invalid.
|
|
15
15
|
- Allowlist reads to prompt-enumerated paths and evidence paths a finding must cite. Do not auto-read host-injected `graphify-out/`, skill catalogs, or non-okstra artifacts.
|
|
16
16
|
- Resolve every `.okstra/...` path against `**Project Root:**`, including when a worktree is present.
|