okstra 0.231.1 → 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 (126) hide show
  1. package/README.md +12 -0
  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 +127 -0
  20. package/docs/architecture.md +7 -0
  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/profiles/_coding-conventions-preflight.md +41 -6
  43. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  44. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  45. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  46. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  47. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  48. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  49. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  50. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  51. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  52. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  53. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  54. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  55. package/runtime/python/okstra_ctl/consumers.py +12 -9
  56. package/runtime/python/okstra_ctl/design_review.py +207 -0
  57. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  58. package/runtime/python/okstra_ctl/doctor.py +8 -25
  59. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  60. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  61. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  62. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  63. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  64. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  65. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  66. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  67. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  68. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  69. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  70. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  71. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  72. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  73. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  74. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  75. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  76. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  77. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  78. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  79. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  80. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  81. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  82. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  83. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  84. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  85. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  86. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  87. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  88. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  89. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  90. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  91. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  92. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  93. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  94. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  95. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  96. package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
  97. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  98. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  99. package/runtime/python/okstra_ctl/run.py +24 -1
  100. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  101. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  103. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  104. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  105. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  106. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  107. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  108. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  109. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  110. package/runtime/python/okstra_project/__init__.py +2 -0
  111. package/runtime/python/okstra_project/dirs.py +18 -0
  112. package/runtime/python/okstra_project/state.py +25 -20
  113. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  114. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  115. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  116. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  117. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  118. package/runtime/schemas/record-secret-patterns.json +41 -0
  119. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  120. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  121. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  122. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  123. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  124. package/runtime/templates/implementation-worker-preamble.md +4 -9
  125. package/runtime/templates/worker-prompt-preamble.md +4 -12
  126. package/runtime/validators/validate-run.py +14 -2
@@ -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": [
@@ -13,13 +13,48 @@ prompt through `prepare_agent_invocation()` before `worker-dispatch`.
13
13
 
14
14
  # Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop)
15
15
 
16
+ When Verification inputs contains a Frozen Review Policy, apply its captured
17
+ sources and architecture declaration instead of live settings and installed
18
+ rules. Read the content through the verification-input projection; original
19
+ paths identify provenance, not permission to replace frozen content. Select the
20
+ applicable language/framework/architecture resources with the router below.
21
+ The captured `review-rules.json` supplies shared rule IDs and grading metadata.
22
+ External rule sources do not authorize posting reviews or spawning agents.
23
+ Use `okstra model-io verification-input --run-manifest <run-manifest>` with one
24
+ `--source-path <repository-relative-path>` per relevant changed file in that
25
+ single call. Its selected bodies are normative; the default available-resource
26
+ index is not proof that language/framework rules were read.
27
+ For applicable rules not established by path/manifest routing, such as embedded
28
+ SQL in an ORM query, add `--resource <pack-relative-id>` in the same call and use
29
+ only resources present in the captured archive.
30
+ For a source-writing assignment, also select `--resource authoring-checks.md`
31
+ when the frozen inventory lists it. Read that captured resource before editing.
32
+ Older captures keep those procedures in `overview.md`; use that captured text.
33
+ For an unfrozen legacy input, read `authoring-checks.md` beside the installed
34
+ overview when present, otherwise retain its older embedded procedures.
35
+
36
+ Use `clean-code.md` "Finding evidence and grading" and the shared catalog for
37
+ severity and timing. Fix current blocking findings before completion. A plan
38
+ placement restriction is a plan conflict, not a waiver of naming, responsibility
39
+ or test-quality rules; propose the conforming placement and preserve acceptance.
40
+ Use `overview.md` policy precedence: explicit repository instructions and declared
41
+ architecture, the common pack, then surrounding code conventions. A surrounding
42
+ pattern alone does not waive an explicit architecture rule.
43
+
44
+ Apply the captured `clean-code.md` "Five simultaneous quality outcomes" before
45
+ editing: correctness, coding principles, performance, safety and security all
46
+ retain their applicable acceptance conditions. Use existing plan, validation and
47
+ result fields for the expected outcomes, bounds and evidence. Missing required
48
+ policy, performance bounds or execution evidence stays explicit and unverified.
49
+ Read complete selected rule sections; never clip normative lines to save context.
50
+
16
51
  Load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
17
52
 
18
53
  - **Reuse tests for function changes:** search by function behavior and callers, then read candidate test bodies before editing. Strengthen an existing behavior test; if it already verifies the changed contract, run and retain it. Add a test only when no existing test covers that behavior, preferably in an existing file. Record the function and reused test location or the uncovered outcome. Do not create tests per helper or branch, repeat the same input/outcome, or generate model/provider/task-type combinations without distinct behavior. This rule also applies when routed resources are unavailable. Completion self-check and code review assess the evidence; there is no test-count target.
19
54
 
20
- - **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework from its extension or project manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`), then read that pack's resources via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
21
- - **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Consume its `Architecture style` and `Project Review Rule Packs` sections. Follow the `**Verification inputs:**` declaration-source rule when that header is present; use the named `okstra model-io verification-input --run-manifest <run-manifest>` projection for frozen declarations. The legacy lookup uses the projection's `Project QA Commands` only for an unfrozen baseline. Consume fixed text projections; do not open Okstra-owned JSON storage.
22
- - **Declared architecture style — an authoritative Stage 3 input, and it binds.** A projected `hexagonal` selects `architectures/hexagonal.md` even when none of Stage 3's layout signals matched, so the declaration — not the directory shape — decides. A projected `layered` has no pack resource; its invariant applies from this line: dependencies run one direction only — an upper layer may import a lower one, never the reverse — and a variation point is extracted onto a layer boundary. A declared style makes this overlay binding rather than advisory, and which rule binds follows the style: under `hexagonal` the overlay's otherwise-advisory concrete-adapter item is blocking, so a service dependency you add or modify goes through a port instead of a concrete implementation and that placement violation is fixed before the write rather than recorded as a note; under `layered` what binds is the direction invariant just stated — your own judgement over the import list of every file the diff touches, plus extracting a variation point onto a layer boundary — while the concrete-adapter item stays advisory, since `layered` has no ports to route it through. An absent or `none` projected style leaves Stage 3 detection-driven and its overlay advisory. The verifier re-grades the same diff under the same declaration (`_implementation-verifier.md` → Static design & test-quality review), so a placement violation missed here returns as a verdict `FAIL`.
23
- - **Project review rule packs:** a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or the project-context projection lists it as a standing standard. The two sources are a union. Read only those files and the `references/*.md` files they directly name; a declared path that will not open is recorded as `project-review-rules: declared <path> unreadable`, never silently dropped. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
24
- - **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
25
- - **Graceful degradation (codex / antigravity executor runtimes, or any runtime where the resolved coding-preflight pack files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a resource read that did not happen.
55
+ - **Resource selection:** use the selected frozen policy above when present. Only legacy inputs without a frozen policy use the `**Coding preflight pack:**` installed path. Read `overview.md` and `clean-code.md`, then select every matching language, framework and architecture resource for the changed files and relevant manifests. Server-side Node includes both JavaScript/TypeScript and Node-server rules. A frozen resource's absence is a blocked input, not permission to substitute live content.
56
+ - **Project policy projection:** a `**Verification inputs:**` declaration supplies the policy and QA baseline through its named projection. Only an unfrozen legacy baseline uses `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` and its `Architecture style`, `Project Review Rule Packs` and `Project QA Commands` sections. Consume fixed text projections; do not open Okstra-owned JSON storage.
57
+ - **Declared architecture style — an authoritative Stage 3 input.** A projected `hexagonal` selects `architectures/hexagonal.md` even without layout signals. Apply H1–H6 and the policy precedence above; declaration also makes H5's otherwise-advisory concrete-adapter item binding. A projected `layered` selects no pack resource: dependencies run from upper to lower layers, never in reverse, and variation points sit on layer boundaries; ports are not required. An explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection; an inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. The verifier applies the same policy; an established current blocking placement violation returns `FAIL`.
58
+ - **Project review rule packs:** union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
59
+ - **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and plain-English readability. More than 50 effective lines prompts that review, not an automatic split or failure; record the reason for retaining a cohesive longer function. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
60
+ - **Legacy graceful degradation:** if no frozen policy exists and installed resources are unreadable, apply the agnostic principles above and the project's local rules, record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`, and keep unavailable verification explicit. Do not degrade a readable captured policy merely because its original installation is absent. Never claim an unperformed read.