okstra 0.231.1 → 0.233.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -271
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +88 -286
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +300 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +45 -25
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +53 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +67 -36
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +45 -20
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +107 -38
|
@@ -60,7 +60,6 @@ Load this **in addition to** [javascript-typescript.md](../languages/javascript-
|
|
|
60
60
|
- `testcontainers` for DBs when the production DB has features (locks, full-text, JSONB, partitioning) you depend on. In-memory fakes lie about behaviour.
|
|
61
61
|
- Test the error paths. Coverage of the happy path only is not coverage.
|
|
62
62
|
|
|
63
|
-
##
|
|
63
|
+
## Verification
|
|
64
64
|
|
|
65
|
-
-
|
|
66
|
-
- `npm run lint && npm test` (or the project's equivalent) must pass before any commit.
|
|
65
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -41,7 +41,7 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
|
|
|
41
41
|
- Framework: **JUnit 5** unless the project uses TestNG or JUnit 4.
|
|
42
42
|
- File suffix: `*Test.java` for unit, `*IT.java` for integration.
|
|
43
43
|
- Method naming: `methodUnderTest_condition_expectedResult` (e.g. `parse_emptyInput_throws`).
|
|
44
|
-
- Use
|
|
44
|
+
- Use JUnit Jupiter's `Assertions` for basic assertions, such as `assertEquals(expected, actual)` instead of `assertTrue(expected == actual)`. AssertJ and Hamcrest provide external fluent assertions; use them when the project already includes them rather than adding a dependency for this style preference.
|
|
45
45
|
- One logical assertion per test. Multiple `assertThat` lines on the *same state* are fine.
|
|
46
46
|
- No `Thread.sleep` in tests — use **Awaitility** for async.
|
|
47
47
|
- Mock at process boundaries only (HTTP, DB, time, randomness). Do not mock value objects or DTOs.
|
|
@@ -57,8 +57,6 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
|
|
|
57
57
|
|
|
58
58
|
What's fine: `@Mock` on collaborators injected into `@InjectMocks`, `verify(collaborator).methodCall(...)` on outcome boundaries (repository save, mailer send, gateway charge).
|
|
59
59
|
|
|
60
|
-
##
|
|
60
|
+
## Verification
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
- `checkstyle`, `spotbugs`, `error-prone` if configured by the project.
|
|
64
|
-
- Run before commit: `./gradlew spotlessApply check` (or the project's equivalent).
|
|
62
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -29,7 +29,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
29
29
|
## TypeScript-specific (mandatory)
|
|
30
30
|
|
|
31
31
|
- `tsconfig.json`: `"strict": true`. No exceptions. `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are recommended.
|
|
32
|
-
-
|
|
32
|
+
- Avoid `any` in production code. If a type is truly unknown, use `unknown` and narrow. The test-only typing exception below still applies.
|
|
33
33
|
- Let inference do its job for locals. Declare explicit types at:
|
|
34
34
|
- Exported function signatures (parameters **and** return type).
|
|
35
35
|
- Public class members.
|
|
@@ -37,7 +37,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
37
37
|
- Use `readonly` for arrays, properties, and parameters that must not mutate.
|
|
38
38
|
- Discriminated unions over loose objects with optional flags. Use a literal `kind` / `type` field.
|
|
39
39
|
- **Never re-declare an authoritative type.** When the domain or a dependency already exports the enum / union for a set of state values (`FontStatus`, `OrderState`), import it — do not hand-maintain a parallel string union or literal list. Before writing a new state type, grep the state literals *and* the intended type name for an existing declaration. A new type's name must say whose values it holds.
|
|
40
|
-
-
|
|
40
|
+
- Prefer type guards (`function isX(v): v is X`) over type assertions (`as X`). Allow `as const` to preserve literal and readonly types. At library or platform boundaries, use a minimal, justified assertion only when inference or narrowing cannot express an established contract. Validate untrusted input before asserting its type.
|
|
41
41
|
- `interface` for object shapes that may be extended; `type` for unions / mapped / conditional types.
|
|
42
42
|
- Generics: meaningful names when single letters are unclear (`TUser`, `TResult`).
|
|
43
43
|
- Never disable rules inline (`// eslint-disable`, `// @ts-ignore`, `// @ts-expect-error`) without a one-line comment explaining why.
|
|
@@ -59,7 +59,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
59
59
|
- File suffix: `*.test.ts` or `*.spec.ts`, colocated with source (`src/foo/bar.ts` → `src/foo/bar.test.ts`).
|
|
60
60
|
- Structure: `describe(unit, () => { it('does X when Y', () => { ... }) })`.
|
|
61
61
|
- **One behaviour per `it` block.**
|
|
62
|
-
- Async tests: `await`
|
|
62
|
+
- Async tests: return or `await` the promise covering asynchronous work and assertions so the runner waits and observes failures. Omitting both can finish the test before assertions run.
|
|
63
63
|
- Mocking: prefer dependency injection over module mocks. When you must mock, use `vi.mock` / `jest.mock` and reset between tests (`beforeEach(() => vi.clearAllMocks())`).
|
|
64
64
|
- React: **React Testing Library**, not Enzyme. Query by role / label / text, not by class or test-id, unless nothing else works.
|
|
65
65
|
- Snapshot tests only for stable, intentional output. Snapshots that "just changed" are noise.
|
|
@@ -86,13 +86,6 @@ expect(repository.save).toHaveBeenCalledWith(id, versionId, expectedInfos, trans
|
|
|
86
86
|
|
|
87
87
|
When the *absence* of a property is the point, assert the exact object or that property's absence directly — a loose `expect.objectContaining` passes even when the property is present. If positional access is genuinely unavoidable, name the index once inside a test helper (`savedInfosOf(repository.save)`) so the meaning lives in one place. Detect with `rg 'mock\.calls'` over the changed test files.
|
|
88
88
|
|
|
89
|
-
##
|
|
89
|
+
## Verification
|
|
90
90
|
|
|
91
|
-
-
|
|
92
|
-
- `eslint --fix .` (style + correctness).
|
|
93
|
-
- `tsc --noEmit` (type check).
|
|
94
|
-
- All three should pass before commit. CI should fail on warnings, not just errors.
|
|
95
|
-
|
|
96
|
-
## Forbidden and Prohibited
|
|
97
|
-
|
|
98
|
-
- never use any type assertions (`as` or ``)
|
|
91
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -62,8 +62,6 @@ Kotlin official coding conventions (kotlinlang.org/docs/coding-conventions.html)
|
|
|
62
62
|
|
|
63
63
|
What's fine: `mockk<Collaborator>()` for injected dependencies, `coEvery {}` on those collaborators, and `verify {}` on outcome boundaries (mailer, gateway, repository write).
|
|
64
64
|
|
|
65
|
-
##
|
|
65
|
+
## Verification
|
|
66
66
|
|
|
67
|
-
-
|
|
68
|
-
- `./gradlew ktlintFormat detekt` if the plugins are configured.
|
|
69
|
-
- Run before commit.
|
|
67
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -163,14 +163,9 @@ When the project is ports-and-adapters, also read [../architectures/hexagonal.md
|
|
|
163
163
|
|
|
164
164
|
What's fine: mocking injected dependencies (`Mock(spec=UserRepository)`, `httpx.MockTransport`), asserting on return values / raised exceptions / emitted events / boundary calls.
|
|
165
165
|
|
|
166
|
-
##
|
|
166
|
+
## Verification
|
|
167
167
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
- `ruff check .` — lint
|
|
171
|
-
- `ruff format --check .` — formatting (or `black --check .`)
|
|
172
|
-
- `mypy .` or `pyright` — type check (if configured)
|
|
173
|
-
- `pytest` — tests
|
|
168
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
174
169
|
|
|
175
170
|
Dependency/project management: `uv`, Poetry, or `pip-tools`. Pin dependencies in application projects; reach for the standard library before adding third-party deps, and avoid importing heavy deps at module-import time when unnecessary.
|
|
176
171
|
|
|
@@ -25,7 +25,6 @@ style_edition = "2024"
|
|
|
25
25
|
|
|
26
26
|
- Indent: **4 spaces**.
|
|
27
27
|
- Max line length: **100** (`rustfmt` default).
|
|
28
|
-
- Always run `cargo fmt` before commit.
|
|
29
28
|
|
|
30
29
|
## Ownership & borrowing
|
|
31
30
|
|
|
@@ -95,11 +94,6 @@ Rust's trait-based DI makes self-mocking rarer than in JVM/JS, but it still happ
|
|
|
95
94
|
|
|
96
95
|
What's fine: `mockall` mocks of injected trait dependencies (`MockHttpClient`, `MockUserRepository`), `unwrap()` in tests for setup that genuinely cannot fail, `assert_eq!` on returned values, `assert_matches!` on returned `Result` / `Option`.
|
|
97
96
|
|
|
98
|
-
##
|
|
97
|
+
## Verification
|
|
99
98
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- `cargo fmt --all` — formatting.
|
|
103
|
-
- `cargo clippy --all-targets --all-features -- -D warnings` — lint (warnings are errors).
|
|
104
|
-
- `cargo check --all-targets` — fast type check.
|
|
105
|
-
- `cargo test --all` — tests.
|
|
99
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -61,8 +61,6 @@ Defaults below target PostgreSQL. MySQL-specific notes are marked.
|
|
|
61
61
|
- Seed test data via factory functions (one per table), not raw `insert` statements copy-pasted into each test.
|
|
62
62
|
- Verify performance assumptions with `explain` in CI for queries flagged as hot.
|
|
63
63
|
|
|
64
|
-
##
|
|
64
|
+
## Verification
|
|
65
65
|
|
|
66
|
-
-
|
|
67
|
-
- Linting / safety: `squawk` (Postgres migration linter — catches missing `concurrently`, locking foot-guns, etc.).
|
|
68
|
-
- Schema diff: `migra` (Postgres), `mysqldiff` (MySQL).
|
|
66
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -1,20 +1,25 @@
|
|
|
1
1
|
# Okstra Coding Preflight
|
|
2
2
|
|
|
3
|
-
These
|
|
3
|
+
These criteria apply to source authors and read-only reviewers. The assignment determines which execution procedures are authorized; shared standards grant no write permissions. Apply every applicable criterion before reporting completion. Conformance remains self-check and review judgment unless a resource names an automated gate; respect its execution owner.
|
|
4
|
+
|
|
5
|
+
Resolve conflicts in this order: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Cite the governing instruction when resolving a conflict. Existing code alone does not waive an explicit architecture rule.
|
|
6
|
+
|
|
7
|
+
Apply [Five simultaneous quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) throughout design, implementation and review. Retain correctness, coding principles, performance, safety and security as separate acceptance conditions in existing evidence.
|
|
4
8
|
|
|
5
9
|
## Core principles
|
|
6
10
|
|
|
7
|
-
1. **DRY —
|
|
8
|
-
2. **KISS — simplest sufficient design
|
|
9
|
-
3. **YAGNI
|
|
10
|
-
4. **Clean Code
|
|
11
|
-
5. **Function
|
|
12
|
-
6. **
|
|
13
|
-
7. **Fix at the cause, inside the change set** — An error surfacing during your work is fixed in the code that produced it — the files you are changing and the modules they directly call. A build/deploy/test failure is NOT a license to edit configuration or manifest files (`package.json`, lockfiles, `tsconfig`, CI config, build scripts) that were already passing before this change; a regression in something previously green almost always lives in the new code, not in long-stable config. If a config/manifest edit looks unavoidable, stop and confirm with the user first — state which file, why the current code can't carry the fix, and what was passing before. *Self-check: every file edited to resolve the error is in the current change set or a module it directly calls; no previously-passing config/manifest was touched to silence the failure without the user's explicit sign-off.* *Example violation: tests fail to import a new module, so you loosen `package.json`/`tsconfig` paths instead of fixing the import in the code you just wrote.*
|
|
11
|
+
1. **DRY** — Share one implementation of a capability; distinguish shared decisions from incidental similarity. See [DRY](clean-code.md#dry--dont-repeat-yourself).
|
|
12
|
+
2. **KISS** — Use the simplest sufficient design. For reuse-driven layers, name the second caller or inline; a cohesive local helper may have one caller. See [KISS](clean-code.md#kiss--keep-it-simple).
|
|
13
|
+
3. **YAGNI** — Cite a current caller, external contract, runtime registration or explicit requirement for each new identifier. See [YAGNI](clean-code.md#yagni--you-arent-gonna-need-it).
|
|
14
|
+
4. **Clean Code** — Use truthful names and explain non-obvious constraints in comments; verify public contract documentation against implementations and callers. See [naming](clean-code.md#meaningful-naming) and [comments](clean-code.md#comments-explain-why-not-what).
|
|
15
|
+
5. **Function size** — Review newly added or substantially edited functions beyond 50 effective body lines; length alone does not require a split. See [function design](clean-code.md#functions-do-one-thing) for counting and evidence.
|
|
16
|
+
6. **Fix the demonstrated cause** — Establish the cause from code and observed evidence. A fix changes only necessary files, including configuration or manifests when justified, within the assignment's authority. Do not weaken code, tests, checks or configuration to hide a regression.
|
|
14
17
|
|
|
15
18
|
## Routed resource selection
|
|
16
19
|
|
|
17
|
-
Read
|
|
20
|
+
Read [clean-code.md](clean-code.md), then evaluate every row in the following three stages in order. Include a resource when any of its conditions matches; accumulate and de-duplicate all matches. State the applied resources and architecture boundary in one sentence.
|
|
21
|
+
|
|
22
|
+
Use the selected frozen policy when supplied; installed paths identify provenance, not replacement content. Read complete applicable sections, including qualifications and examples, using semantic section ranges rather than clipped lines. An available-resource index does not establish that selected rules were read.
|
|
18
23
|
|
|
19
24
|
### Stage 1 — Language (iterate all rules)
|
|
20
25
|
|
|
@@ -33,44 +38,26 @@ Read `clean-code.md` for the language-agnostic principles, then select language,
|
|
|
33
38
|
|---|---|
|
|
34
39
|
| [frameworks/node-server.md](frameworks/node-server.md) | `package.json` or its dependencies/scripts show server-side Node work (`express`, `fastify`, `nestjs`, server entrypoints, API routes, CLI services); or a touched file is a Node runtime module |
|
|
35
40
|
|
|
36
|
-
Node.js server work
|
|
41
|
+
For Node.js server work, load both JavaScript/TypeScript and Node server resources.
|
|
37
42
|
|
|
38
43
|
### Stage 3 — Architecture (iterate all rules)
|
|
39
44
|
|
|
45
|
+
Declared architecture takes precedence over layout signals. `hexagonal` selects the resource below; `layered` applies its dependency-direction invariant without selecting that resource; explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection.
|
|
46
|
+
|
|
40
47
|
| Resource | Include when any condition matches |
|
|
41
48
|
|---|---|
|
|
42
|
-
| [architectures/hexagonal.md](architectures/hexagonal.md) | ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
|
|
43
|
-
|
|
44
|
-
If a layout looks hexagonal but is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer. Architecture overlays default to none when no rule matches.
|
|
45
|
-
|
|
46
|
-
If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code — do not invent a default.
|
|
49
|
+
| [architectures/hexagonal.md](architectures/hexagonal.md) | the project explicitly declares hexagonal architecture; or ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
|
|
47
50
|
|
|
48
|
-
|
|
51
|
+
For an undeclared style with a non-standard layout that looks hexagonal, ask once which architecture and domain boundary apply, and record the answer. Undeclared overlays default to none when no rule matches.
|
|
49
52
|
|
|
50
|
-
|
|
51
|
-
- [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone + one identifier one meaning per file), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
|
|
52
|
-
- [ ] **Mutation and state boundaries** (`clean-code.md`): decide on the direct identifier, not a status/flag proxy; capture before-state in one snapshot ahead of the mutating boundary; update only this work's owned fields on an existing row; re-read state before calling a zero-affected-rows write success or failure; put priority-between-inputs in a named domain function; keep error messages to what was observed.
|
|
53
|
-
- [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process or acts on its behalf: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; new entry points enforce the project's operation-specific access policy, including shared, administrative, and explicitly public access where applicable; protect secrets and limit personal-data disclosure as specified in `clean-code.md`, including authorized data responses and credential issuance; no eval or unsafe deserialization of input.
|
|
54
|
-
- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change and project rules permit it. Record the exact waived behavior or check and its unverified coverage. That waiver applies to the corresponding branch-test, branch-deletion, and resource-bound checks in this pack; it does not waive unrelated checks, weaken existing tests, or establish verified coverage.
|
|
55
|
-
- [ ] **Function changes reuse tests first:** before changing a function, search its behavior and callers and read candidate tests. If a behavior test exists, strengthen it in place; if it already verifies the changed contract, run and retain it. Add a test only when that behavior has no existing test, preferring an existing file. Record the function, reused test location, or uncovered outcome that justifies a new test. Do not generate one test per function, helper, or branch, or expand model/provider/task-type combinations without distinct outcomes. This is checked in the completion self-check and code review, not by a test-count target.
|
|
56
|
-
- [ ] **Existing tests surveyed (run this before planning any new test):** for every surface this change touches, `grep -rln` the candidate test files, list their test names, then READ the bodies of the ones that could overlap. A list of names does not tell you what a test asserts, and behavioural overlap does not collide on names — treat a clean name search as unfinished, not as a clear result. Record per surface: `extend <path:line>` / `new (nothing covers <behaviour>)` / `retire <path:line> (behaviour moved to <where>)`. A new test or test file with no survey line is unfinished work. The survey may change the design — moving the seam so existing tests keep passing beats adding parallel ones. Carry out a `retire` verdict in the same commit, on behavioural grounds only: the behaviour it asserted is gone, or a new test asserts it more strongly through the same seam. "Looks similar" / "touches the same file" is not grounds; without grounds the test stays, because a silent coverage loss costs more than one extra test.
|
|
57
|
-
- [ ] **Testing discipline:** apply the recorded testing waiver only to its stated scope. For tests written or edited, the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each unwaived branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
|
|
58
|
-
- [ ] **Third-party wrapper (when this change wraps a library call):** the wrapper adds behaviour the library does not already provide — read the installed library source before keeping a recovery branch — no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
|
|
59
|
-
- [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`, no changed domain file importing outward (ORM / framework / adapters / services), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory — record it with the port sketch; blocking when the project declares `architecture.style = hexagonal` in `.okstra/project.json` — fix before write, never record-and-pass).
|
|
60
|
-
- [ ] **Existing code searched — by capability, not by name:** `grep` the identifier you are about to add AND the behaviour it performs (call sites, domain literals, error strings, the shape of the data it returns). A capability that already exists under a different name is the duplication this check exists to catch, and an identifier grep alone never finds it — name-level uniqueness is not evidence of absence. Record per new unit: the search terms used, the nearest existing implementation found, and the verdict `extend <path:line>` / `new (nothing covers <behaviour>)`. No survey line, no new unit.
|
|
61
|
-
- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this resource pack on conflict.**
|
|
53
|
+
If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code.
|
|
62
54
|
|
|
63
|
-
##
|
|
55
|
+
## Applying criteria within the assignment
|
|
64
56
|
|
|
65
|
-
|
|
57
|
+
Read-only reviewers evaluate these standards against source and authorized execution evidence. Report violations and unavailable checks to the lead; do not repair source, run a writing formatter or perform authoring procedures. Execute only checks the assignment authorizes.
|
|
66
58
|
|
|
67
|
-
|
|
68
|
-
- [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
|
|
69
|
-
- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static) — **run by the implementation verifier, never by the author of the diff.** This sweep is the manual half and ends at your own reading; the detector run and its `qa/self-mock-*.json` sidecar are the verifier's duty (`prompts/profiles/_implementation-verifier.md` §"Self-mock detection"), and it is that sidecar's absence that BLOCKS at `validate-run.py` — on the verifier's report, not on your diff. Running the detector yourself does not pre-satisfy the gate: the sidecar is outside an executor attempt's `writePolicy.artifactPolicy.allowedPaths`, so writing it makes okstra's write audit close the attempt as `error` (`artifact-root change exceeds batch policy union`), and the verifier writes the same file again under its own duty.
|
|
70
|
-
- [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
|
|
59
|
+
Workers authorized to change source also read [authoring-checks.md](authoring-checks.md) before editing. For a frozen policy, select that resource from its archive with `--resource authoring-checks.md`. Older captures may retain those procedures in this overview; use their captured text without substituting installed files.
|
|
71
60
|
|
|
72
|
-
##
|
|
61
|
+
## Verification commands
|
|
73
62
|
|
|
74
|
-
-
|
|
75
|
-
- This preflight does **not** replace repo-local rules. Repo rules win on conflict.
|
|
76
|
-
- This preflight does **not** cover every language. If the target language is missing, stop and ask.
|
|
63
|
+
Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive focused behavior and failure tests, cause verification or explicit project-required mutation checks; use the selective mutation criteria in [Testing discipline](clean-code.md#testing-discipline).
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "1.0",
|
|
3
|
+
"blockingSeverities": ["must-fix", "should-fix"],
|
|
4
|
+
"blockingTiming": "now",
|
|
5
|
+
"gradingReference": "clean-code.md#Finding evidence and grading",
|
|
6
|
+
"rules": {
|
|
7
|
+
"S1": ["structural", "clean-code.md#DRY — Don't Repeat Yourself"],
|
|
8
|
+
"S2": ["structural", "clean-code.md#KISS — Keep It Simple"],
|
|
9
|
+
"S3": ["structural", "clean-code.md#SOLID"],
|
|
10
|
+
"S4": ["structural", "clean-code.md#YAGNI — You Aren't Gonna Need It"],
|
|
11
|
+
"S5": ["structural", "architectures/hexagonal.md#Rule H1"],
|
|
12
|
+
"S6": ["structural", "architectures/hexagonal.md#Rule H2"],
|
|
13
|
+
"S7": ["structural", "architectures/hexagonal.md#Rule H3"],
|
|
14
|
+
"S8": ["structural", "architectures/hexagonal.md#Rule H4"],
|
|
15
|
+
"S9": ["structural", "architectures/hexagonal.md#Rule H5"],
|
|
16
|
+
"S10": ["structural", "architectures/hexagonal.md#Rule H6"],
|
|
17
|
+
"M1": ["semantic", "clean-code.md#Meaningful naming"],
|
|
18
|
+
"M2": ["semantic", "clean-code.md#Functions do one thing"],
|
|
19
|
+
"M3": ["semantic", "clean-code.md#Comments explain *why*, not *what*"],
|
|
20
|
+
"T1": ["state-and-tests", "clean-code.md#Mutation and state boundaries"],
|
|
21
|
+
"T2": ["state-and-tests", "clean-code.md#No self-mocking"],
|
|
22
|
+
"T3": ["state-and-tests", "clean-code.md#Behavioral, not implementation tests"],
|
|
23
|
+
"T4": ["state-and-tests", "clean-code.md#Test data must actually separate the paths"],
|
|
24
|
+
"G1": ["general", "clean-code.md#Trace what this change can do wrong"],
|
|
25
|
+
"G2": ["general", "clean-code.md#Wrapping a third-party call"],
|
|
26
|
+
"G3": ["general", "clean-code.md#Untrusted input and security"],
|
|
27
|
+
"G4": ["general", "clean-code.md#Resource bounds need their own regression test"],
|
|
28
|
+
"G5": ["general", "overview.md#Routed resource selection"]
|
|
29
|
+
}
|
|
30
|
+
}
|
|
@@ -3,39 +3,36 @@
|
|
|
3
3
|
"id": "code-reviewer",
|
|
4
4
|
"roleId": "verifier",
|
|
5
5
|
"responsibilities": [
|
|
6
|
-
"
|
|
6
|
+
"Judge every assigned census cell against the frozen policy, acceptance conditions and five quality outcomes."
|
|
7
7
|
],
|
|
8
8
|
"requiredConduct": [
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"Return one compact Coverage Verdicts table row per assigned target/group cell. Explicitly account for every shared-catalog rule ID under Checked, N/A with an inline applicability reason, or Findings with finding IDs. Share one literal inspected target-source path:line per row. Do not expand pack bullets into separate verdict rows, use all-checked claims, or mark unread rules checked.",
|
|
13
|
-
"Inspect before accounting: evaluate changed constructs against every applicable canonical clause, follow result mappings and the work done by existing callees, and identify findings before compressing the coverage table. Passing tests and linters do not establish conformance to every assigned rule."
|
|
9
|
+
"Read the frozen diff, whole target files and affected callers, callees, contracts and tests before producing verdicts. Specialty limits verdict ownership, not context reads. Read complete applicable rule clauses; do not clip their text or replace frozen policy with installed files.",
|
|
10
|
+
"Use shared execution evidence only when its head and inputs match. Inspect assertions, failure and boundary cases and self-mocking where assigned. Ask the lead for necessary additional execution; do not launch duplicate suites.",
|
|
11
|
+
"On follow-ups, inspect the selected correction range and its impact before accepting this slot's carry candidates under a matching comparison base and policy. Supporting context outside the supplied census creates no independent targets; full inspection means that census. Reopen contradicted conclusions, distinguish inspected from inherited cells, retain earlier finding dispositions separately, and use full inspection when the boundary is uncertain."
|
|
14
12
|
],
|
|
15
13
|
"decisionPrinciples": [
|
|
16
|
-
"
|
|
17
|
-
"
|
|
14
|
+
"Use demonstrated impact and likelihood to grade actionable findings. Follow documented policy rather than preference, trace shared decisions before claiming duplication, and recommend the smallest correction.",
|
|
15
|
+
"Passing tests, valid output accounting and correct current outputs do not establish all five quality outcomes or excuse an applicable design violation."
|
|
18
16
|
],
|
|
19
17
|
"authorityAndBoundaries": [
|
|
20
|
-
"
|
|
18
|
+
"Keep census membership, rule ownership and the frozen comparison range unchanged. Do not broaden the diff or redesign unrelated code."
|
|
21
19
|
],
|
|
22
20
|
"evidenceStandards": [
|
|
23
|
-
"Each finding
|
|
24
|
-
"
|
|
25
|
-
"For checked G2, G3 and G5 rules in general cells, the Evidence field includes source-cited clean observations after ::, keyed by rule ID. G2 traces dependency outcome meanings through diagnostic values; G3 identifies workload dimensions, downstream work and limits before that work; G5 names the applicable canonical clauses and observed conformance. Missing or unsupported inspection stays unaccounted instead of clean."
|
|
21
|
+
"Each finding identifies its cell, source evidence, assigned rule or behavior, consequence and feasible correction. An execution-error establishes a reachable state, expected outcome and wrong result. A design-violation establishes an applicable rule and concrete design impact without requiring a runtime failure.",
|
|
22
|
+
"A clean verdict explains inspected evidence. For checked G2/G3/G5, preserve the calibration's source-cited observations after ::. Missing inspection or required execution stays unaccounted; unavailable performance bounds stay unverified."
|
|
26
23
|
],
|
|
27
24
|
"collaborationContract": [
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"Keep verdicts independent from other reviewers and the author. Do not echo a finding without verifying it, suppress a unique defect for consistency, or resolve cross-cell overlap by changing identifiers; return overlap information to the lead."
|
|
25
|
+
"Only the assigned review function belongs to this invocation. Return your own verdicts without spawning reviewers; the lead owns dispatch, audits and team consolidation.",
|
|
26
|
+
"Return out-of-assignment evidence and aggregation conflicts to their owner without changing cell identities or borrowing another team's verdicts."
|
|
31
27
|
],
|
|
32
28
|
"completionCriteria": [
|
|
33
|
-
"
|
|
29
|
+
"Return one grouped Coverage Verdicts row per assigned cell. Account for each expected rule exactly once under Checked, reasoned N/A or Findings, with the required target-source anchor and finding links. Preserve identifiers; no omitted rule is implicitly clean.",
|
|
30
|
+
"Report incomplete or blocked quality checks explicitly. Complete accounting authenticates the response shape, not the truth of its conclusions."
|
|
34
31
|
],
|
|
35
32
|
"prohibitions": [
|
|
36
|
-
"Do not
|
|
33
|
+
"Do not mark unread criteria checked or classify unsupported candidates as findings."
|
|
37
34
|
],
|
|
38
35
|
"blockedStateReporting": [
|
|
39
|
-
"
|
|
36
|
+
"Name each unevaluable cell, the missing source, policy, bound or execution evidence, the inspection attempted and the conclusion that remains unavailable."
|
|
40
37
|
]
|
|
41
38
|
}
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
"Maintain a fresh context from the execution session, and weigh the diff rather than the confidence of the narrative describing it. Do not ask the executor to supply the verdict, silently repair its work, or coordinate a passing conclusion; return actionable findings to the lead with enough evidence for a bounded correction."
|
|
22
22
|
],
|
|
23
23
|
"completionCriteria": [
|
|
24
|
+
"When Frozen Design Review is supplied, independently return every cell/rule verdict and structured finding against its exact base, head, policy and census fingerprints; missing accounting prevents acceptance. This is checked by design-review evidence validation, not by another worker's response.",
|
|
24
25
|
"Every assigned criterion and required check has an explicit pass, fail, or blocked disposition; material regressions and test-quality risks have been examined; and the overall verdict follows from the recorded evidence."
|
|
25
26
|
],
|
|
26
27
|
"prohibitions": [
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schemaVersion": "1.0",
|
|
3
|
+
"id": "interface-reviewer",
|
|
4
|
+
"roleId": "verifier",
|
|
5
|
+
"responsibilities": [
|
|
6
|
+
"Independently judge whether a proposed interface design serves every approved use case and requirement through sound domain boundaries and public signatures, before any interface code is written."
|
|
7
|
+
],
|
|
8
|
+
"requiredConduct": [
|
|
9
|
+
"Map every approved requirement to at least one use case and every use case to the boundaries and signatures that serve it. Read the existing modules, callers and conventions the design touches, and check each signature's inputs, outputs, failure results and ownership against that use case and the surrounding code."
|
|
10
|
+
],
|
|
11
|
+
"decisionPrinciples": [
|
|
12
|
+
"Prefer the smallest interface that serves the approved use cases and fits existing project boundaries. Distinguish a missing or unserved use case, a boundary that leaks another layer's concern and a signature that cannot express a required outcome from a stylistic preference, and leave scope decisions to the approved specification."
|
|
13
|
+
],
|
|
14
|
+
"authorityAndBoundaries": [
|
|
15
|
+
"Review the assigned design against the approved specification and existing code without rewriting either. Do not add requirements, redesign unrelated modules or write interface code."
|
|
16
|
+
],
|
|
17
|
+
"evidenceStandards": [
|
|
18
|
+
"Each finding names the requirement or use case affected, the boundary or signature at fault, the existing code it conflicts with as path:line where one exists, and the consequence for implementation or callers. A clean verdict states what was mapped and checked."
|
|
19
|
+
],
|
|
20
|
+
"collaborationContract": [
|
|
21
|
+
"Return findings and the verdict to the lead with their evidence. Do not negotiate the design with its author or decide whether the specification itself should change."
|
|
22
|
+
],
|
|
23
|
+
"completionCriteria": [
|
|
24
|
+
"Every requirement and use case has been traced to the design, every public signature has been checked against the use cases it serves, and unmapped items, defects and clean checks are all recorded."
|
|
25
|
+
],
|
|
26
|
+
"prohibitions": [
|
|
27
|
+
"Do not pass a design with an unserved use case or unmapped requirement, turn naming or style preferences into defects, or propose implementation details beyond the interface."
|
|
28
|
+
],
|
|
29
|
+
"blockedStateReporting": [
|
|
30
|
+
"Identify the missing specification, use-case table or source context, the mapping that cannot be completed, the attempts made and the requirements or use cases left unverified."
|
|
31
|
+
]
|
|
32
|
+
}
|
|
@@ -1,17 +1,26 @@
|
|
|
1
1
|
# Host orchestration rules
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
`
|
|
3
|
+
The phase catalog explicitly declares which task types require host rules:
|
|
4
|
+
`implementation` and `implementation-planning`. Their canonical files live in
|
|
5
|
+
the owning phase packages as `host-rules.md`; an asset root without a Python
|
|
6
|
+
package uses this directory's `<task-type>.md` path. A missing declared file is
|
|
7
|
+
an installation error. Undeclared task types get an empty host-rules path,
|
|
8
|
+
regardless of whether a file exists.
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
The wizard exposes the selected canonical file's absolute path as
|
|
11
|
+
`outcome.orchestration.hostRulesPath`. The `okstra-run` skill reads a non-empty
|
|
12
|
+
path after confirmation and before the first `render-bundle`, so waiver and
|
|
13
|
+
recovery instructions are available even when preparation fails. It does not
|
|
14
|
+
embed the implementation or planning rules in its body.
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
16
|
+
`scripts/okstra_ctl/run.py` copies declared rules into the prepared instruction
|
|
17
|
+
set as `host-orchestration-rules.md`. This frozen copy governs resumed work and
|
|
18
|
+
stage chaining. The launch prompt still requires the lead to read it within the
|
|
19
|
+
run; a pre-prepare read of the canonical file does not satisfy the implementation
|
|
20
|
+
session read gate. Legacy prepared runs with no frozen file retain the existing
|
|
21
|
+
session-conformance compatibility behavior.
|
|
13
22
|
|
|
14
|
-
The
|
|
23
|
+
The frozen copy exists because a rule that lives only in the conversation is
|
|
15
24
|
one compaction away from gone: a DEV-10400 run operated for five turns on a
|
|
16
25
|
skill body truncated mid-Step-5 and nothing signalled the loss. On disk, the
|
|
17
26
|
rules survive compaction and `validators/validate_session_conformance.py` can
|
|
@@ -191,11 +191,12 @@ The **default is full re-verification**. Narrow this re-run to the impacted stag
|
|
|
191
191
|
4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
|
|
192
192
|
5. **`mode == "incremental"`** → scope every worker dispatch prompt to `reverify_stages` only (the downstream closure of the impacted stages). Do NOT re-analyze `carry_stages` — their prior plan-item verdicts are carried forward verbatim (see `scripts/okstra_ctl/phases/implementation_planning/profile.md` "Cross-verification mode" and `prompts/lead/convergence.md` "Convergence scope"). When the pin in step 0 was `auto`, this is the decision — do not upgrade it to full.
|
|
193
193
|
6. **`mode == "unresolved"`** → ask the user for stage numbers; re-enter step 3 with those numbers in `--impacted`. Do not fall back to full. Do not record `unresolved` as `incrementalDecision`. Then continue from the new `mode`.
|
|
194
|
-
7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --narrative
|
|
194
|
+
7. **Merge carried-forward verdicts.** In `incremental` mode the report writer receives the carried stage rows as a packet source and is told, in its own authoring contract, to copy them unchanged — you do not repeat that instruction to it. After `okstra plan-items seed --run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} --narrative <this run's reportNarrativePath> --state ...`, the lead runs:
|
|
195
195
|
```
|
|
196
196
|
okstra incremental-carry \
|
|
197
|
+
--run-manifest {{RUN_MANIFEST_RELATIVE_PATH}} \
|
|
197
198
|
--prev-data {{RUN_REPORTS_RELATIVE_PATH}}/final-report-implementation-planning-<prev-seq>.data.json \
|
|
198
|
-
--cur-narrative <this run's
|
|
199
|
+
--cur-narrative <this run's reportNarrativePath> \
|
|
199
200
|
--state <this run's plan-body-verification state> \
|
|
200
201
|
--prev-seq <prev-seq> \
|
|
201
202
|
--decision {{INCREMENTAL_DECISION_STATE_RELATIVE_PATH}} \
|
|
@@ -45,6 +45,8 @@ Run Input is the only Phase 1 source for task identity, work category, workflow
|
|
|
45
45
|
|
|
46
46
|
Use the `Worker Roster` section for dispatch and model assignment. Use `Artifact Paths` for prompt, result, report, status, validator, and resume locations. Use `Configuration References` for the task-level Markdown resources. Do not derive sibling paths from file names or sequence counters.
|
|
47
47
|
|
|
48
|
+
Use `Report authoring format` as the current run's declared writer syntax and `Report writer input` as its exact stored authoring path, including when the lead writes that input directly.
|
|
49
|
+
|
|
48
50
|
Use the `Current phase` labels as the workflow view. Rules for `nextRecommendedPhase` are maintained by [report-writer](./report-writer.md); do not re-derive phase routing here.
|
|
49
51
|
|
|
50
52
|
## Output
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Overview
|
|
4
4
|
|
|
5
|
-
The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report
|
|
5
|
+
The lead orchestrates the selected AI workers against a prepared task bundle, collects their independent outputs, supervises convergence, and ensures the final report is produced. When `Report writer worker` is in the selected roster, that worker authors the report input in the run manifest's declared `reportAuthoringFormat`; report assembly publishes the final record from role-owned inputs. The lead never substitutes its own reasoning for a worker result and never bypasses a rostered report writer.
|
|
6
6
|
|
|
7
7
|
The lead owns the approval decision ledger and writes it only through `okstra approval-decision`. The activity recorder owns the activity ledger. Runtime adapters own team state and usage. The convergence engine owns convergence state and the completed plan-body result. The design-surface detector owns the design-preparation snapshot. Report assembly validates these inputs and publishes `final-report-*.data.json` once; a failure is returned to the owner named in its diagnostic.
|
|
8
8
|
|
|
@@ -57,7 +57,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
57
57
|
| `okstra model-io run-input --run-manifest <path>` | Read run identity, worker roster, model assignments, and artifact paths instead of opening the run manifest | `context-loader` "Step 3" |
|
|
58
58
|
| `okstra model-io active-context-input --project-root <dir> --run-manifest <path>` | Read the prior executor base ref for an incremental re-run | launch prompt "Incremental re-verification" |
|
|
59
59
|
| `okstra incremental-scope --prev-data <path>` | Decide re-verify vs carry-forward stages on a clarification re-run | launch prompt "Incremental re-verification" |
|
|
60
|
-
| `okstra incremental-carry --prev-data <path> --prev-seq <seq> --cur-narrative <
|
|
60
|
+
| `okstra incremental-carry --run-manifest <current-run-manifest> --prev-data <path> --prev-seq <seq> --cur-narrative <reportNarrativePath>` | Merge carried-forward plan-item verdicts after `plan-items seed`; then repeat `plan-items prepare --state`, `prompt` and `validate-prepared --state` using that same manifest | launch prompt "Incremental re-verification" |
|
|
61
61
|
| `okstra stage-map <task-key>` | Read the prior Stage Map and done stages before re-planning | host orchestration rules (implementation-planning) |
|
|
62
62
|
| `okstra stage-close <task-key> --stage <N> --from-commit <sha> [--supersede-failed <reason>]` | Close a stage whose work already landed outside okstra, or a `failed` stage whose failure no longer applies |
|
|
63
63
|
| `okstra stage-reopen <task-key> --stage <N> --reason <why> [--evidence <report>]` | Reopen a `done` stage for a fix run, e.g. after a `blocked` final-verification of that stage | host orchestration rules (implementation-planning) |
|
|
@@ -160,19 +160,19 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
|
|
|
160
160
|
|---|---|---|
|
|
161
161
|
| `okstra agent-prompt check-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Check a report-writer corrections ledger before a corrective dispatch | `report-writer` "Corrective report-writer dispatch" |
|
|
162
162
|
| `okstra agent-prompt apply-corrections --project-root <dir> --run-manifest <path> --corrections <path>` | Apply a ledger that `check-corrections` reported `mechanical: true`, without a writer round | `report-writer` "Corrective report-writer dispatch" |
|
|
163
|
-
| `okstra design-snapshot --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths come from
|
|
163
|
+
| `okstra design-snapshot --run-manifest <path> --narrative <path> --output <path>` | Complete the design-surface detector snapshot; both paths and the authoring format come from that run manifest | `report-writer` "Implementation-planning sequence" |
|
|
164
164
|
| `okstra plan-items prepare --run-manifest <path> --narrative <path>` | Extract this round's plan items (add `--state <path>` after a self-fix or `incremental-carry`, `--tie-vote` for a critic tie round) | `plan-body-verification` "Round protocol" |
|
|
165
165
|
| `okstra plan-items prompt --run-manifest <path>` | Print the plan-items block placed verbatim in every verifier prompt | `plan-body-verification` "Round protocol" |
|
|
166
166
|
| `okstra plan-items validate-prepared --run-manifest <path> --narrative <path>` | Validate the prepared envelope before dispatch; pass the same `--state` the last `prepare` used | `plan-body-verification` "Round protocol" |
|
|
167
|
-
| `okstra plan-items seed --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
|
|
168
|
-
| `okstra plan-items extract --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted | `plan-body-verification` "Round protocol" |
|
|
167
|
+
| `okstra plan-items seed --run-manifest <path> --narrative <path>` | Create the `planItems[]` rows a round lands in | `plan-body-verification` "Round protocol" |
|
|
168
|
+
| `okstra plan-items extract --run-manifest <path> --narrative <path> --output <path>` | Re-extract plan items after a round and re-verify any item whose subject shifted; use the input path declared by that run manifest | `plan-body-verification` "Round protocol" |
|
|
169
169
|
| `okstra plan-items correction-prompt --run-manifest <path> --state <path> --worker <id>` | Put its output first in a `worker-correction` re-dispatch prompt | `plan-body-verification` "Round protocol" |
|
|
170
170
|
| `okstra plan-items collect-verdicts --items <path> --result <worker>=<path> --output <path>` | Read a round's responses into a verdicts envelope; never parse them by hand | `plan-body-verification` "Round protocol" |
|
|
171
171
|
| `okstra plan-items apply-verdicts --state <path> --round <N> --result <worker>=<path>` | Record the round's verdicts | `plan-body-verification` "Round protocol" |
|
|
172
172
|
| `okstra plan-items complete-round --state <path> --run-manifest <path> --round <N>` | Record the completed round | `plan-body-verification` "Round protocol" |
|
|
173
173
|
| `okstra plan-items next-dispatch --state <path>` | Decide whether the round opens another worker batch | `plan-body-verification` "Round protocol" |
|
|
174
174
|
| `okstra plan-items resolve-dissent --state <path> --item <P-id> --decision-file <path>` | Record an evidence-based lead decision after the single self-fix | `plan-body-verification` "Round protocol" |
|
|
175
|
-
| `okstra plan-verify --
|
|
175
|
+
| `okstra plan-verify --run-manifest <path> --narrative <reportNarrativePath> --state <path>` | Score the plan-body gate before report assembly, using that run's declared input format; never tally votes in a script | `plan-body-verification` "Round protocol" |
|
|
176
176
|
| `okstra worktree-lock --worktree <dir> --command <text>` | Lead minor fix (implementation only, never in a run marked `verificationEvidenceVersion`): re-run each Tier 1 command and failing verifier check that covers a fixed finding, in the stage worktree, under its lock | `_implementation-deliverable.md` "Lead minor fix" |
|
|
177
177
|
|
|
178
178
|
### Phase 7 — persist
|
|
@@ -590,7 +590,7 @@ If convergence is disabled, `seed`/`finalize` produce the auto-disabled final st
|
|
|
590
590
|
|
|
591
591
|
### Authoring ownership (BLOCKING)
|
|
592
592
|
|
|
593
|
-
If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only `
|
|
593
|
+
If `Report writer worker` is in the selected roster (`recommendedWorkers` / `resultContract.workerRoles`), Lead dispatches it to author only the input at the run manifest's `reportNarrativePath`, its worker-result pointer, and its audit sidecar. `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and the existing narrative line grammar. Use the declared path and format, including its `.json` or `.md` extension. The worker may read the complete run context but cannot write `final-report-*.data.json` or another role's ledger. After every required input exists, Phase 7 runs report assembly, which validates the role-owned inputs and atomically publishes the report record once. Phase 7 then renders the human HTML from that record. Contract v2 artifacts remain readable but no new run writes them. **Enforced:** report-writer dispatch completion paths in `scripts/okstra_ctl/dispatch_state.py`, granted artifacts in `scripts/okstra_ctl/dispatch_core.py`, and `scripts/okstra_ctl/report_assembly.py` `assemble_report`.
|
|
594
594
|
|
|
595
595
|
Before constructing the dispatch prompt, the lead MUST:
|
|
596
596
|
|