okstra 0.231.0 → 0.232.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.
Files changed (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -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
- ## Formatter / linter / tools
63
+ ## Verification
64
64
 
65
- - Same as JS / TS: `prettier`, `eslint`, `tsc`.
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 **AssertJ** or JUnit's `assertThat` for fluent assertions; avoid bare `assertTrue(a == b)`.
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
- ## Formatter / linter to run
60
+ ## Verification
61
61
 
62
- - `google-java-format` (preferred) or the `spotless` Gradle/Maven plugin.
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
- - **Never** use `any`. If a type is truly unknown, use `unknown` and narrow.
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
- - Type guards (`function isX(v): v is X`) over casts (`as X`). Casts are a last resort.
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` every promise. Returning a promise without `await` hides assertion failures.
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
- ## Formatter / linter to run
89
+ ## Verification
90
90
 
91
- - `prettier --write .` (formatting).
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
- ## Formatter / linter to run
65
+ ## Verification
66
66
 
67
- - **ktlint** and / or **detekt**.
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
- ## Required tooling
166
+ ## Verification
167
167
 
168
- Run before declaring a Python change complete:
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
- ## Required tooling
97
+ ## Verification
99
98
 
100
- Run before any commit:
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
- ## Tools
64
+ ## Verification
65
65
 
66
- - Formatting: `pg_format`, `sqlfluff`, `sql-formatter`.
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 rules apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
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 — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
8
- 2. **KISS — simplest sufficient design** — Add reusable abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when current callers require them. For reuse-driven extraction, name the second caller now; otherwise inline. A local helper with one caller is appropriate when it names a distinct step in a mixed-level function or brings a body under the 50-line cap. Keep that helper local rather than introducing a reusable layer. Project-required architecture boundaries still apply. *Example violation: extracting a shared `formatUserName()` module used by exactly one call site, "in case we need it elsewhere".*
9
- 3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier serves a current internal use, an established external contract, a runtime entry point, or an explicit user requirement. Cite the caller, contract, registration, or requirement; a hypothetical future consumer is not evidence.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
10
- 4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; replace comments that merely narrate executable code with clearer names. Reserve implementation comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Interface documentation may state caller-visible contracts that names and types cannot express, such as error versus mismatch results or required work for missing inputs; verify those claims against implementations and callers. Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
11
- 5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
12
- 6. **Simplest conforming approach** — When choosing how to implement or fix something, pick the simplest, most direct solution path that still conforms to the project's architecture and established conventions. This is broader than KISS (#2): KISS bounds abstraction; this bounds the whole approach. Simplicity never licenses bending the structure or a convention — rule out non-conforming paths first, then take the plainest of what remains. Self-check: name the architecture/convention boundary the chosen approach respects; if a simpler path respects it too, take that one.
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 `clean-code.md` for the language-agnostic principles, then select language, framework, and architecture resources in three ordered stages. Each stage is a list of rules; a rule has one or more conditions; if ANY condition matches, include that rule's resource. Iterate EVERY rule in a stage — do not stop at the first match, because one change set can touch multiple languages, frameworks, or architectures. De-duplicate the final set, then state in one sentence which resources you applied (e.g., *"Applying TS + Node server + hexagonal; domain at src/domain/."*).
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 also matches Stage 1's JavaScript/TypeScript rule — load both `languages/javascript-typescript.md` and `frameworks/node-server.md`.
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
- ## Mandatory pre-write checks (every language)
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
- - [ ] Language reference read for this turn.
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
- ## Completion sweep (before declaring a multi-file change done)
55
+ ## Applying criteria within the assignment
64
56
 
65
- Per-file checks miss cross-cutting issues; each commit can be individually clean while the sum violates DRY. Before saying "done":
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
- - [ ] **Domain-literal sweep:** `grep -rn` every domain enum value / predicate you added or touched in WHERE clauses, filters, or branches. The same literal at 2+ I/O sites is a *candidate* scattered decision — ask: would these sites change together when the business rule changes? Same decision → consolidate into one named constant or query builder in the domain layer and make every site reference it. Different decisions that merely share a value → leave them separate; coupling incidental duplication is worse than the repetition. (The identifier grep above does NOT catch this — sweep *values*, not just names.)
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
- ## Boundaries
61
+ ## Verification commands
73
62
 
74
- - This preflight does **not** auto-format. Run the project's formatter yourself.
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 applicable behavior-test, branch-deletion or cause-verification obligations.
@@ -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
- "Return an evidence-backed verdict for every assigned review census cell, acting as a correctness, maintainability and documented-convention gate, and without changing the census or the code under review."
6
+ "Judge every assigned census cell against the frozen policy, acceptance conditions and five quality outcomes."
7
7
  ],
8
8
  "requiredConduct": [
9
- "On follow-up reviews, inspect the correction delta and its impact closure. Treat carry candidates as proposals: independently search affected callers, callees, contracts and tests before attesting inheritance from this slot's verified prior verdicts. Reopen candidates for newly discovered effects or evidence of a real defect; fall back to full inspection when the boundary is uncertain. Account for this slot's full assigned census and distinguish inspected from inherited cells.",
10
- "Inspect every assigned cell's actual diff and full context: whole target files, enclosing definitions, affected callers and callees, contracts, outcome consumers and related tests at the frozen head. Follow transitive effects as needed. An assigned specialty limits verdict ownership, not context reads. Route suspected issues outside the assignment to the lead without changing the census. Preserve the cell identifier and return concrete findings or an evidence-backed clean verdict.",
11
- "Use the lead's shared test execution evidence, checking its head and inputs. Review test assertions, failure and boundary cases and self-mocking where assigned. Distinguish inspected tests from executed tests, report missing or failed verification, and ask the lead for any additional necessary execution rather than launching duplicate suites or editing code.",
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
- "Report only actionable defects with a demonstrated consequence. Calibrate priority from impact and likelihood, distinguish correctness from preference, avoid duplicate findings across cells, and recommend the smallest fix that addresses the established problem.",
17
- "Distinguish personal preference from an explicit repository or routed-pack convention. A concrete violation of a documented convention can be a nit even when runtime behavior is correct. Trace shared decision functions before claiming that repeated orchestration duplicates a business rule."
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
- "Review only the provided census and fixed comparison range. Do not add, merge, split, omit, or reinterpret cells; do not edit source, broaden the diff, or redesign unrelated code."
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 must identify its cell, exact code evidence, violated behavior or project standard, consequence, and feasible correction. A clean verdict must name what was inspected and why no actionable issue was found.",
24
- "Classify each finding as execution-error or design-violation. An execution error establishes a reachable failure and wrong result. A design violation identifies the applicable assigned rule, code evidence, and concrete design or maintenance impact; it does not require a runtime failure. Both kinds include a feasible fix; preference alone is insufficient.",
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
- "The spawning coordinator divides the received full census and delivers each subset to its responsible child. Each child investigates that assignment and returns explicit coverage and findings. The coordinator compares all responses with both the child assignments and the full census, sends omissions back to the same logical child with its prior results, and repeats until nothing remains unaccounted for. Only then return the consolidated model report; blocked or incomplete coverage is never a completed review.",
29
- "Honor the assigned coordinator or specialty role without recursive delegation. A model-team coordinator owns the full census, itself spawns the six same-provider/model specialty subagents, collects and verifies their completions, requests their gap-fills, and consolidates their rule statuses and findings with child provenance before returning its model report. Do not transfer child spawning or consolidation to the orchestrator. Correct any aggregation discrepancy in the spawning coordinator's report. A specialty subagent inspects only its assigned rule subset and does not spawn further reviewers. Preserve independence between model teams; never borrow another team's verdict to fill a gap.",
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. Delegation and model-team consolidation require an explicit task assignment; otherwise return your own verdicts without spawning reviewers.",
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
- "Every grouped cell accounts for all expected shared-catalog rule IDs exactly once, all findings are prioritized and evidenced, and blocked or unaccounted rules identify what prevents evaluation. Preserve the census IDs; do not silently infer clean verdicts from missing rule IDs."
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 reinterpret, merge, omit, or add census cells; report speculative concerns as defects; use style preference as a blocking standard; edit the reviewed code; or claim a cell clean without inspecting its assigned evidence."
33
+ "Do not mark unread criteria checked or classify unsupported candidates as findings."
37
34
  ],
38
35
  "blockedStateReporting": [
39
- "Identify each unevaluable cell, the missing source, diff, runtime evidence, or governing standard, the inspection attempted, and the review conclusion that remains unavailable."
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": [
@@ -52,7 +52,7 @@ Configure this in the `convergence` block of `task-manifest.json`. If the block
52
52
  | `maxRounds` | `2` (range 1–3) | Maximum number of re-verification rounds. A second round runs only for a finding whose first round produced no usable vote or a tie the critic decides (§"Adversarial classification"); with `1`, a tie is `contested`. Lead resolves the effective value when the manifest omits the key and records it in `config.effectiveMaxRounds` of the convergence state artifact. |
53
53
  | `adversarial` | `true` | Always `true`: every phase runs Phase 5.5 in **adversarial mode** (see §"Adversarial Verification Mode") — verifiers actively try to refute each finding, the burden of proof sits on the claim, and `verificationMode` is `"full-reanalysis"` scoped to the finding's cited evidence. `okstra convergence prepare-groups` writes both values regardless of the task manifest, and `seed` refuses a grouping with `adversarial: false` (**Enforced:** `_parse_config` in `scripts/okstra_ctl/convergence_engine.py`). |
54
54
 
55
- **Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the run's selected roster (`resultContract.workerRoles`) holds fewer than 2 analyser workers — the user selected one analyser, or `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phase 5.5, and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). An `implementation-planning` run with one planner still runs the plan-body verification round; that planner's single vote settles each item (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**), "A one-analyser roster"). **Enforced:** `scripts/okstra_ctl/convergence_engine.py` `seed_working_state` stops with `auto-disabled` below two analysis workers, and `validators/validate-run.py` `single_verifier_advisories` records the missing cross-model check as an advisory.
55
+ **Auto-disable rule (BLOCKING).** Convergence requires ≥2 analyser workers to produce a meaningful consensus tally. When the run's selected roster (`resultContract.workerRoles`) holds fewer than 2 analyser workers — the user selected one analyser, or `release-handoff` (zero analyser workers, lead-only) — the lead MUST treat `convergence.enabled` as `false` for that run regardless of manifest configuration, skip Phase 5.5, and record `finalState: "converged"` with `totalRounds: 0`, `round2SkippedReason: "auto-disabled"`, an empty `roundHistory`, and an explanatory note in `config` (e.g. `"autoDisabled": "fewer-than-two-analysers"`). An `implementation-planning` run with one planner still runs the plan-body verification round; that planner's single vote settles each item (`plan-body-verification` (the absolute path in **Okstra Runtime Resources**), "A one-analyser roster"). When the selected roster holds two or more, the seeded count is of those analysers that returned an accepted result, not of workers a group cites: a verifier no group cites still counts, and it re-verifies the queued findings it did not originate. **Enforced:** `scripts/okstra_ctl/convergence.py` `_group_workers` puts every analysis-role execution with an accepted result into the grouping's `workers`, `scripts/okstra_ctl/convergence_engine.py` `seed_working_state` stops with `auto-disabled` below two analysis workers, and `validators/validate-run.py` `single_verifier_advisories` records the missing cross-model check as an advisory.
56
56
 
57
57
  ## Finding Category
58
58
 
@@ -97,7 +97,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
97
97
  - For bullet/numbered findings, parse `[TICKETID: <id>]` from the item title.
98
98
  - Items with multiple tickets (e.g. `TICKET-123, TICKET-456`) expand to a set of ticket keys.
99
99
  - Items tagged `unknown` keep the literal `unknown` as their ticket key.
100
- 2. For each finding, record the summary, evidence (file path, line number, basis), the discovering worker, **the worker-internal item ID that worker assigned** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. Persist the item ID as `findings[].discoveredBy.<worker>.itemId` and each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` tables read this verbatim into their `Source items` columns; without it the synthesised `C-NNN` row loses its link back to the original worker wording.
100
+ 2. For each finding, record the summary, evidence (file path, line number, basis), the discovering worker, **the worker-internal item ID that worker assigned** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. Persist the item ID as `findings[].discoveredBy.<worker>.itemId` and each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` tables read this verbatim into their `Source items` columns; without it the synthesised `C-NNN` row loses its link back to the original worker wording. A worker item that carries no id cannot be cited: do not mint one for it, since `okstra convergence seed` refuses an id the worker's result does not contain. Record the omission with `okstra error-log append-observed --error-type contract-violation` against that worker; the worker still counts toward the analyser roster (Auto-disable rule above).
101
101
  3. The lead groups findings based on semantic similarity AND ticket-set equality:
102
102
  - Same semantics + same ticket set across 2+ workers → one multi-source group.
103
103
  - Same semantics but disjoint ticket sets → separate groups (do NOT over-merge across tickets).
@@ -128,7 +128,7 @@ Follow this protocol exactly:
128
128
  1. Run `okstra convergence seed --groups <groups> --run-manifest <current-run-manifest> --work-state <work> --final-state <final> --migration-dir <state/migrations>` for a v2 worker roster. `--run-manifest` must be the exact current manifest named by the groups document's `runManifestPath`; a previous run from the same task is not interchangeable. `seed` refuses a grouping that cites a worker whose initial attempt the mutation audit discarded (`contract-failed-unattributed`, `mutation-present-unresolved`) — the result file is still on disk, but the ledger says it was never accepted. Re-dispatch that worker as a new invocation and cite the new result, or leave it out of the grouping. **Enforced:** `discarded_worker_errors` in `scripts/okstra_ctl/convergence_provenance.py`, called by `_seed`. Omit the flag for a legacy v1 roster. A `reuse-final` action means validate the existing final and continue to Phase 6. `create-work`, `resume-work`, and `restart-round0` continue with planning.
129
129
  2. Run `okstra convergence plan-round --work-state <work> --plan <round-plan>`. This is read-only with respect to the working state. Its stdout JSON carries `round` and `inputQueueSize`; on a `dispatch` plan the round's `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` line copies those two values — never count the queue by hand. **Enforced:** `_plan_round` in `scripts/okstra_ctl/convergence.py`, the retired Python suite.
130
130
  3. Every plan carries `dispatchable`: `true` on an `action: "dispatch"` plan, `false` on an `action: "finalize"` plan. When the plan action is `dispatch`, create exactly one reverify prompt for each `dispatches[]` row and dispatch it through the selected runtime adapter. Its findings are exactly that row's `findingIds`.
131
- 4. Run `okstra convergence collect-results --plan <round-plan> --result <worker>=<path>… --run-manifest <current-run-manifest> --output convergence-round-<N>-results-<task-type>-<seq>.json`. Each planned worker's terminal outcome and `durationMs` come from the manifest's attempt ledger, not from the lead: an attempt still `started` refuses the collect — run `okstra team await` first so the attempt closes — and a worker whose attempt did not close `ok` cannot contribute a vote even if its result file exists. **Enforced:** `_dispatch_rows_from_manifest` in `scripts/okstra_ctl/convergence.py`. Then run `okstra convergence apply-round --work-state <work> --plan <round-plan> --results <round-results>`.
131
+ 4. Run `okstra convergence collect-results --plan <round-plan> --run-manifest <current-run-manifest> --output convergence-round-<N>-results-<task-type>-<seq>.json`. Each planned worker's terminal outcome and `durationMs` come from the manifest's attempt ledger, not from the lead: an attempt still `started` refuses the collect — run `okstra team await` first so the attempt closes — and a worker whose attempt did not close `ok` cannot contribute a vote even if its result file exists. A worker whose attempt closed `ok` is read from the result path that attempt recorded; `--result <worker>=<path>` (repeatable) overrides it for that worker. The collect refuses a completed worker when the ledger recorded no result path or the recorded file is missing, and names the worker. **Enforced:** `_dispatch_rows_from_manifest` and `_recorded_results` in `scripts/okstra_ctl/convergence.py`, tested by `tests/verification/test_convergence_collect_results.py`. Then run `okstra convergence apply-round --work-state <work> --plan <round-plan> --results <round-results>`.
132
132
  5. Repeat `plan-round` and `apply-round` until the plan action is `finalize`. A `finalize` plan is **never dispatched**: it carries `dispatchable: false`, an empty `dispatches[]`, and a `note` naming the next command. Its `round` is only the `<N>` in `convergence-round-<N>-plan-<task-type>-<seq>.json` — not a round to run — so do not open reverify workers for it. **Enforced:** `okstra convergence apply-round` refuses a non-dispatch plan and returns the gate's closing reason with the remedy (`scripts/okstra_ctl/convergence_engine.py` `apply_round_results`).
133
133
  6. When the coverage critic is enabled, convert its verification batch to the canonical `dispatches[]` / `gaps[]` result shape and run `okstra convergence apply-critic-gaps --work-state <work> --results <critic-results>` exactly once. The reducer, not the lead, merges verified gaps.
134
134
  7. Run `okstra convergence finalize --work-state <work> --output <final>`.
@@ -143,7 +143,7 @@ Every `okstra` command the lead documents cite, grouped by phase, each spelled w
143
143
  | `okstra convergence seed --groups <path> --work-state <path> --final-state <path> --migration-dir <dir>` | Create, resume, or recover the working state | `convergence` "Round 0" |
144
144
  | `okstra convergence plan-round --work-state <path> --plan <path>` | Write the next round's dispatch plan | `convergence` "Round 1-N" |
145
145
  | `okstra convergence reverify-prompt --run-manifest <path> --plan <path> --worker <worker>` | Print one worker's reverify instructions; never compose them by hand | `convergence` "Re-verification Dispatch" |
146
- | `okstra convergence collect-results --plan <path> --result <worker>=<path> --run-manifest <path> --output <path>` | Read one round's responses into the apply-round input | `convergence` "Round 1-N" |
146
+ | `okstra convergence collect-results --plan <path> [--result <worker>=<path>] --run-manifest <path> --output <path>` | Read one round's responses into the apply-round input | `convergence` "Round 1-N" |
147
147
  | `okstra convergence apply-round --work-state <path> --plan <path> --results <path>` | Apply a round's results | `convergence` "Round 1-N" |
148
148
  | `okstra convergence critic-prompt --run-manifest <path>` | Print the critic instructions (acceptance on `final-verification`, coverage elsewhere); dispatch concurrently with the first reverify round | `convergence` "Coverage critic pass" |
149
149
  | `okstra convergence critic-verify-prompt --run-manifest <path> --gaps <path> --worker <worker>` | Print one analyser's gap-verification or acceptance-candidate instructions | `convergence` "Gap verification", "Acceptance critic pass" |
@@ -265,7 +265,7 @@ Record each checkpoint with `okstra lead-progress append --project-root <dir> --
265
265
 
266
266
  Some checkpoints are recorded by the command that performs the step, because that command holds the fact the line states:
267
267
 
268
- - `okstra team dispatch` (on a `terminalBackend: cmux-pane` run) and `okstra worker-dispatch` / `okstra codex-dispatch` record `phase-3-team-create using implicit team` when the dispatch is the one that writes the implicit-team marker into team-state (no `teamCreate` recorded yet), `phase-4-dispatch` for each `initial` job, and `phase-6-synthesis` on the run's first report-writer dispatch.
268
+ - `okstra team dispatch` (on a `terminalBackend: cmux-pane` run) and `okstra worker-dispatch` / `okstra codex-dispatch` record `phase-3-team-create using implicit team` when the dispatch is the one that writes the implicit-team marker into team-state (no `teamCreate` recorded yet), `phase-4-dispatch` for each `initial` job and for each job of an implementation correction round — its `correction-r<N>` executor and verifier dispatches and each `reverify-r<k>` whose invocation id carries `-correction-r<N>-` — and `phase-6-synthesis` on the run's first report-writer dispatch.
269
269
  - On a `cmux-pane` run `okstra team await` records `phase-5-poll` on entry and again when the counts changed; `okstra team await` there and `okstra worker-dispatch` record `phase-5-collect worker=<role> status=<terminal-status>` for each `initial` dispatch they settled — the settlement is the result verification: the required artifact exists, the mutation audit passed and the result is linked to its dispatch, or the attempt closed as `error` / `timeout`. A retried attempt counts once its retry settles.
270
270
  - On a `cmux-pane` run `okstra team reclaim` records `phase-batch-cleanup`.
271
271
  - The team commands record nothing on any other `terminalBackend`: a run that dispatches with `okstra team dispatch` and waits with `okstra team await` there appends the team commands' checkpoints itself. `okstra worker-dispatch` still records its own, as listed above.
@@ -34,7 +34,7 @@ Resolution `checkRefs` name existing `A-NNN` activity rows. Those activity rows
34
34
 
35
35
  Two rules the assembled record is checked against, both learned from the 2026-09-05 audit of shipped pages:
36
36
 
37
- - **An empty value is empty, never a null literal.** A prose field with nothing to say is omitted or left `""`. `"None"`, `"null"`, `"undefined"` and `"NaN"` are serialisation artefacts the page prints as text (`tradeoffMatrix` cells in nlpvibe planning-009…014). The lowercase `none` an option's `addedWork`/`directionChange` uses to mean "nothing" is a contract token and stays. **Enforced:** `validators/validate-run.py` `_validate_no_null_literals_in_prose` fails a prose field holding one of those literals.
37
+ - **An empty value is empty, never a null literal.** A prose field with nothing to say is omitted or left `""`. `"None"`, `"null"`, `"undefined"` and `"NaN"` are serialisation artefacts the page prints as text (`tradeoffMatrix` cells in nlpvibe planning-009…014). The lowercase `none` an option's `addedWork`/`directionChange` uses to mean "nothing" is a contract token and stays. **Enforced:** `validators/validate-run.py` `_validate_no_null_literals_in_prose` fails a prose field holding one of those literals, and `scripts/okstra_ctl/approval_decisions.py` `DecisionOption` refuses one in an option's `addedWork`/`directionChange` when the lead records the option.
38
38
  - **Citations name rows the reader can reach.** `evidenceRefs`, `supportingEvidence` and the other citation lists carry the record's own ids (`E-`, `CV-`, `D-`, `EA-`, `C-`, `A-`) or a `path:line`. A worker's own finding number (`F-NNN`) reaches the reader only through a promoted `evidence.primary[]` row whose `sourceItems` name it as `<worker>:F-NNN` — the page links a bare `F-NNN` to that row when exactly one row carries it, and leaves it as dead text otherwise. **Enforced:** `_unbridged_worker_finding_refs` in `validators/validate-run.py` warns on every bare `F-NNN` no `sourceItems` entry carries; the narrative rule `_validate_no_opaque_id_references` already fails one in a reader-facing sentence.
39
39
 
40
40
  ## Report-writer dispatch
@@ -170,7 +170,7 @@ After each worker attempt returns (regardless of role), Lead MUST verify the can
170
170
  - The deterministic provider process returned an explicit `*_RESULT_MISSING` sentinel.
171
171
  - The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/antigravity sub-agent forwarded raw stdout despite the contract.
172
172
  - The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
173
- - A reverify (`reverify-r<N>`) result file exists but does not parse as verdict blocks — a missing `**Explanation**`, an unknown verdict token, an unreadable file. This one is settled by the dispatcher, not by you: `okstra_ctl.dispatch_state.unusable_result_defect` counts it as a missing artifact at collection, so the batch re-dispatches it and, if the second attempt fails the same way, closes the attempt as failed. `okstra convergence collect-results` then reads that worker's round status as `error` from the ledger and the engine records its findings as `verification-error` — do not hand-edit the result, and do not omit the worker from `--result` while its attempt still reads `ok`, which `apply-round` refuses with "missing vote for completed worker".
173
+ - A reverify (`reverify-r<N>`) result file exists but does not parse as verdict blocks — a missing `**Explanation**`, an unknown verdict token, an unreadable file. This one is settled by the dispatcher, not by you: `okstra_ctl.dispatch_state.unusable_result_defect` counts it as a missing artifact at collection, so the batch re-dispatches it and, if the second attempt fails the same way, closes the attempt as failed. `okstra convergence collect-results` then reads that worker's round status as `error` from the ledger and the engine records its findings as `verification-error` — do not hand-edit the result, and do not leave that worker out of the collect while its attempt still reads `ok`: collect-results reads its recorded result file even without `--result`, and refuses it while it does not parse.
174
174
  - `okstra worker-liveness --team-state <path> --worker <id>` reports a **CLI-wrapper** worker `did-not-launch` after its launch grace. The probe resolves both wrapper artifacts through `wrapper_status`; a missing guessed filename is not this verdict. Use the persisted probe outcome before retrying.
175
175
  - `okstra worker-liveness --team-state <path> --worker <id>` reports an **in-process** worker `stalled` — its registered audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent in-process worker until its deadline. The same selector serves both worker kinds — the sidecar is reused when a worker is re-dispatched, so the probe needs the row's `startedAt` to tell the previous attempt's last heartbeat apart from this dispatch's silence. A budget breach is not a verdict on its own: the probe re-reads the sidecar after half that stage's budget and reports `stalled` only when the newest heartbeat has not advanced, so an unhealthy verdict costs that confirmation window before it returns. That window is what separates a worker inside one long uninterruptible tool call — which cannot append a heartbeat at all — from a worker that died, and measuring it is the probe's job, not yours: do not second-guess a verdict by checking mtimes yourself. Tune it with `--stall-confirm <seconds>`; `0` restores the immediate verdict.
176
176
  - The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
@@ -4,9 +4,10 @@
4
4
  - `rationale` — why this option is on the board, as long as the reason needs.
5
5
  - `reach` — exactly one of `in-repo` or `cross-repo`.
6
6
  - `scopeEffects` — optional tokens drawn from `{new-schema, deferrable}`.
7
- - `addedWork` — the work this choice creates that the other choices do not. Name the files, stages, or commands; do not substitute a cost adjective.
8
- - `directionChange` — what this choice reverses: an approved plan item, a recorded decision, an earlier answer. Name that item. When it reverses nothing, say so.
7
+ - `addedWork` — the work this choice creates that the other choices do not. Name the files, stages, or commands; do not substitute a cost adjective. When it creates none, write `none`.
8
+ - `directionChange` — what this choice reverses: an approved plan item, a recorded decision, an earlier answer. Name that item. When it reverses nothing, write `none`.
9
9
  - `disposition` — the effect of selecting the option. Use `select` for `user-decision`. Use `accept-risk` on any classification, including `correctness-critical`, when the user ends the gate and leaves the DISAGREE on the record. Use `request-revision` or `reject` when the option sends the plan back.
10
+ - `addedWork` and `directionChange` never hold `None`, `null`, `undefined` or `NaN`; the page would print them as text. **Enforced:** `scripts/okstra_ctl/approval_decisions.py` `DecisionOption` refuses them when `okstra approval-decision open` records the option.
10
11
  - report assembly derives `approvalContext`, status, and resolution. `approvalContext` contains only `classification`, `unblockCondition`, and `recommendedDisposition`; it never copies plan or activity identifiers.
11
12
  - a `C-NNN` you name outside the row itself must be a row that exists. One place is checked: a `blocked` `endStateCoverage` row's `blockedBy.ref`, when its `kind` is `clarification` — see each phase profile's `blockedBy` rule and `validators/validate-run.py` `_validate_end_state_blocked_by`. Everywhere else — `coveredBy`, `rationale`, `verdictCard.nextStep`, `finalVerdict.nextStep`, `humanSummary.actions[]`, `recommendedNextSteps[].text` — is free prose and stays uncheckable: a shipped report legitimately writes `C-057 through C-068 are applied or carried` or `C-201 does not apply`, and a validator scanning those fields for ids would fail 15 of the 56 reports on disk. There it is on you not to send a reader after an id with no row. An id an earlier run already answered reaches this report as a carried decision — prepare seeds `carriedDecisions[]` from the run's carry-in record, and `okstra approval-decision carry` admits one that record does not answer — never by citing it bare. `crossVerification` rows are numbered `CV-NNN` so a `C-NNN` has exactly one meaning.
12
13
  - the three impact fields answer three different questions — how far the change reaches, what new work it creates, and what it overturns. Someone choosing between options needs all three, so never fold them into one field: whichever axis is easiest to write would silently stand in for the other two.