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.
- package/README.md +12 -0
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +127 -0
- package/docs/architecture.md +7 -0
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +85 -281
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +71 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +24 -1
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +25 -20
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- 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
|
-
##
|
|
63
|
+
## Verification
|
|
64
64
|
|
|
65
|
-
-
|
|
66
|
-
- `npm run lint && npm test` (or the project's equivalent) must pass before any commit.
|
|
65
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -41,7 +41,7 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
|
|
|
41
41
|
- Framework: **JUnit 5** unless the project uses TestNG or JUnit 4.
|
|
42
42
|
- File suffix: `*Test.java` for unit, `*IT.java` for integration.
|
|
43
43
|
- Method naming: `methodUnderTest_condition_expectedResult` (e.g. `parse_emptyInput_throws`).
|
|
44
|
-
- Use
|
|
44
|
+
- Use JUnit Jupiter's `Assertions` for basic assertions, such as `assertEquals(expected, actual)` instead of `assertTrue(expected == actual)`. AssertJ and Hamcrest provide external fluent assertions; use them when the project already includes them rather than adding a dependency for this style preference.
|
|
45
45
|
- One logical assertion per test. Multiple `assertThat` lines on the *same state* are fine.
|
|
46
46
|
- No `Thread.sleep` in tests — use **Awaitility** for async.
|
|
47
47
|
- Mock at process boundaries only (HTTP, DB, time, randomness). Do not mock value objects or DTOs.
|
|
@@ -57,8 +57,6 @@ Google Java Style Guide is the default. If the project ships its own (`CONTRIBUT
|
|
|
57
57
|
|
|
58
58
|
What's fine: `@Mock` on collaborators injected into `@InjectMocks`, `verify(collaborator).methodCall(...)` on outcome boundaries (repository save, mailer send, gateway charge).
|
|
59
59
|
|
|
60
|
-
##
|
|
60
|
+
## Verification
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
- `checkstyle`, `spotbugs`, `error-prone` if configured by the project.
|
|
64
|
-
- Run before commit: `./gradlew spotlessApply check` (or the project's equivalent).
|
|
62
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -29,7 +29,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
29
29
|
## TypeScript-specific (mandatory)
|
|
30
30
|
|
|
31
31
|
- `tsconfig.json`: `"strict": true`. No exceptions. `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are recommended.
|
|
32
|
-
-
|
|
32
|
+
- Avoid `any` in production code. If a type is truly unknown, use `unknown` and narrow. The test-only typing exception below still applies.
|
|
33
33
|
- Let inference do its job for locals. Declare explicit types at:
|
|
34
34
|
- Exported function signatures (parameters **and** return type).
|
|
35
35
|
- Public class members.
|
|
@@ -37,7 +37,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
37
37
|
- Use `readonly` for arrays, properties, and parameters that must not mutate.
|
|
38
38
|
- Discriminated unions over loose objects with optional flags. Use a literal `kind` / `type` field.
|
|
39
39
|
- **Never re-declare an authoritative type.** When the domain or a dependency already exports the enum / union for a set of state values (`FontStatus`, `OrderState`), import it — do not hand-maintain a parallel string union or literal list. Before writing a new state type, grep the state literals *and* the intended type name for an existing declaration. A new type's name must say whose values it holds.
|
|
40
|
-
-
|
|
40
|
+
- Prefer type guards (`function isX(v): v is X`) over type assertions (`as X`). Allow `as const` to preserve literal and readonly types. At library or platform boundaries, use a minimal, justified assertion only when inference or narrowing cannot express an established contract. Validate untrusted input before asserting its type.
|
|
41
41
|
- `interface` for object shapes that may be extended; `type` for unions / mapped / conditional types.
|
|
42
42
|
- Generics: meaningful names when single letters are unclear (`TUser`, `TResult`).
|
|
43
43
|
- Never disable rules inline (`// eslint-disable`, `// @ts-ignore`, `// @ts-expect-error`) without a one-line comment explaining why.
|
|
@@ -59,7 +59,7 @@ Airbnb JavaScript Style Guide is the common baseline. The project's `.eslintrc(.
|
|
|
59
59
|
- File suffix: `*.test.ts` or `*.spec.ts`, colocated with source (`src/foo/bar.ts` → `src/foo/bar.test.ts`).
|
|
60
60
|
- Structure: `describe(unit, () => { it('does X when Y', () => { ... }) })`.
|
|
61
61
|
- **One behaviour per `it` block.**
|
|
62
|
-
- Async tests: `await`
|
|
62
|
+
- Async tests: return or `await` the promise covering asynchronous work and assertions so the runner waits and observes failures. Omitting both can finish the test before assertions run.
|
|
63
63
|
- Mocking: prefer dependency injection over module mocks. When you must mock, use `vi.mock` / `jest.mock` and reset between tests (`beforeEach(() => vi.clearAllMocks())`).
|
|
64
64
|
- React: **React Testing Library**, not Enzyme. Query by role / label / text, not by class or test-id, unless nothing else works.
|
|
65
65
|
- Snapshot tests only for stable, intentional output. Snapshots that "just changed" are noise.
|
|
@@ -86,13 +86,6 @@ expect(repository.save).toHaveBeenCalledWith(id, versionId, expectedInfos, trans
|
|
|
86
86
|
|
|
87
87
|
When the *absence* of a property is the point, assert the exact object or that property's absence directly — a loose `expect.objectContaining` passes even when the property is present. If positional access is genuinely unavoidable, name the index once inside a test helper (`savedInfosOf(repository.save)`) so the meaning lives in one place. Detect with `rg 'mock\.calls'` over the changed test files.
|
|
88
88
|
|
|
89
|
-
##
|
|
89
|
+
## Verification
|
|
90
90
|
|
|
91
|
-
-
|
|
92
|
-
- `eslint --fix .` (style + correctness).
|
|
93
|
-
- `tsc --noEmit` (type check).
|
|
94
|
-
- All three should pass before commit. CI should fail on warnings, not just errors.
|
|
95
|
-
|
|
96
|
-
## Forbidden and Prohibited
|
|
97
|
-
|
|
98
|
-
- never use any type assertions (`as` or ``)
|
|
91
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -62,8 +62,6 @@ Kotlin official coding conventions (kotlinlang.org/docs/coding-conventions.html)
|
|
|
62
62
|
|
|
63
63
|
What's fine: `mockk<Collaborator>()` for injected dependencies, `coEvery {}` on those collaborators, and `verify {}` on outcome boundaries (mailer, gateway, repository write).
|
|
64
64
|
|
|
65
|
-
##
|
|
65
|
+
## Verification
|
|
66
66
|
|
|
67
|
-
-
|
|
68
|
-
- `./gradlew ktlintFormat detekt` if the plugins are configured.
|
|
69
|
-
- Run before commit.
|
|
67
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -163,14 +163,9 @@ When the project is ports-and-adapters, also read [../architectures/hexagonal.md
|
|
|
163
163
|
|
|
164
164
|
What's fine: mocking injected dependencies (`Mock(spec=UserRepository)`, `httpx.MockTransport`), asserting on return values / raised exceptions / emitted events / boundary calls.
|
|
165
165
|
|
|
166
|
-
##
|
|
166
|
+
## Verification
|
|
167
167
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
- `ruff check .` — lint
|
|
171
|
-
- `ruff format --check .` — formatting (or `black --check .`)
|
|
172
|
-
- `mypy .` or `pyright` — type check (if configured)
|
|
173
|
-
- `pytest` — tests
|
|
168
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
174
169
|
|
|
175
170
|
Dependency/project management: `uv`, Poetry, or `pip-tools`. Pin dependencies in application projects; reach for the standard library before adding third-party deps, and avoid importing heavy deps at module-import time when unnecessary.
|
|
176
171
|
|
|
@@ -25,7 +25,6 @@ style_edition = "2024"
|
|
|
25
25
|
|
|
26
26
|
- Indent: **4 spaces**.
|
|
27
27
|
- Max line length: **100** (`rustfmt` default).
|
|
28
|
-
- Always run `cargo fmt` before commit.
|
|
29
28
|
|
|
30
29
|
## Ownership & borrowing
|
|
31
30
|
|
|
@@ -95,11 +94,6 @@ Rust's trait-based DI makes self-mocking rarer than in JVM/JS, but it still happ
|
|
|
95
94
|
|
|
96
95
|
What's fine: `mockall` mocks of injected trait dependencies (`MockHttpClient`, `MockUserRepository`), `unwrap()` in tests for setup that genuinely cannot fail, `assert_eq!` on returned values, `assert_matches!` on returned `Result` / `Option`.
|
|
97
96
|
|
|
98
|
-
##
|
|
97
|
+
## Verification
|
|
99
98
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- `cargo fmt --all` — formatting.
|
|
103
|
-
- `cargo clippy --all-targets --all-features -- -D warnings` — lint (warnings are errors).
|
|
104
|
-
- `cargo check --all-targets` — fast type check.
|
|
105
|
-
- `cargo test --all` — tests.
|
|
99
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -61,8 +61,6 @@ Defaults below target PostgreSQL. MySQL-specific notes are marked.
|
|
|
61
61
|
- Seed test data via factory functions (one per table), not raw `insert` statements copy-pasted into each test.
|
|
62
62
|
- Verify performance assumptions with `explain` in CI for queries flagged as hot.
|
|
63
63
|
|
|
64
|
-
##
|
|
64
|
+
## Verification
|
|
65
65
|
|
|
66
|
-
-
|
|
67
|
-
- Linting / safety: `squawk` (Postgres migration linter — catches missing `concurrently`, locking foot-guns, etc.).
|
|
68
|
-
- Schema diff: `migra` (Postgres), `mysqldiff` (MySQL).
|
|
66
|
+
Follow [Verification commands](../overview.md#verification-commands) for repository-configured tools, affected scope, and check timing.
|
|
@@ -1,20 +1,25 @@
|
|
|
1
1
|
# Okstra Coding Preflight
|
|
2
2
|
|
|
3
|
-
These
|
|
3
|
+
These criteria apply to source authors and read-only reviewers. The assignment determines which execution procedures are authorized; shared standards grant no write permissions. Apply every applicable criterion before reporting completion. Conformance remains self-check and review judgment unless a resource names an automated gate; respect its execution owner.
|
|
4
|
+
|
|
5
|
+
Resolve conflicts in this order: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Cite the governing instruction when resolving a conflict. Existing code alone does not waive an explicit architecture rule.
|
|
6
|
+
|
|
7
|
+
Apply [Five simultaneous quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) throughout design, implementation and review. Retain correctness, coding principles, performance, safety and security as separate acceptance conditions in existing evidence.
|
|
4
8
|
|
|
5
9
|
## Core principles
|
|
6
10
|
|
|
7
|
-
1. **DRY —
|
|
8
|
-
2. **KISS — simplest sufficient design
|
|
9
|
-
3. **YAGNI
|
|
10
|
-
4. **Clean Code
|
|
11
|
-
5. **Function
|
|
12
|
-
6. **
|
|
13
|
-
7. **Fix at the cause, inside the change set** — An error surfacing during your work is fixed in the code that produced it — the files you are changing and the modules they directly call. A build/deploy/test failure is NOT a license to edit configuration or manifest files (`package.json`, lockfiles, `tsconfig`, CI config, build scripts) that were already passing before this change; a regression in something previously green almost always lives in the new code, not in long-stable config. If a config/manifest edit looks unavoidable, stop and confirm with the user first — state which file, why the current code can't carry the fix, and what was passing before. *Self-check: every file edited to resolve the error is in the current change set or a module it directly calls; no previously-passing config/manifest was touched to silence the failure without the user's explicit sign-off.* *Example violation: tests fail to import a new module, so you loosen `package.json`/`tsconfig` paths instead of fixing the import in the code you just wrote.*
|
|
11
|
+
1. **DRY** — Share one implementation of a capability; distinguish shared decisions from incidental similarity. See [DRY](clean-code.md#dry--dont-repeat-yourself).
|
|
12
|
+
2. **KISS** — Use the simplest sufficient design. For reuse-driven layers, name the second caller or inline; a cohesive local helper may have one caller. See [KISS](clean-code.md#kiss--keep-it-simple).
|
|
13
|
+
3. **YAGNI** — Cite a current caller, external contract, runtime registration or explicit requirement for each new identifier. See [YAGNI](clean-code.md#yagni--you-arent-gonna-need-it).
|
|
14
|
+
4. **Clean Code** — Use truthful names and explain non-obvious constraints in comments; verify public contract documentation against implementations and callers. See [naming](clean-code.md#meaningful-naming) and [comments](clean-code.md#comments-explain-why-not-what).
|
|
15
|
+
5. **Function size** — Review newly added or substantially edited functions beyond 50 effective body lines; length alone does not require a split. See [function design](clean-code.md#functions-do-one-thing) for counting and evidence.
|
|
16
|
+
6. **Fix the demonstrated cause** — Establish the cause from code and observed evidence. A fix changes only necessary files, including configuration or manifests when justified, within the assignment's authority. Do not weaken code, tests, checks or configuration to hide a regression.
|
|
14
17
|
|
|
15
18
|
## Routed resource selection
|
|
16
19
|
|
|
17
|
-
Read
|
|
20
|
+
Read [clean-code.md](clean-code.md), then evaluate every row in the following three stages in order. Include a resource when any of its conditions matches; accumulate and de-duplicate all matches. State the applied resources and architecture boundary in one sentence.
|
|
21
|
+
|
|
22
|
+
Use the selected frozen policy when supplied; installed paths identify provenance, not replacement content. Read complete applicable sections, including qualifications and examples, using semantic section ranges rather than clipped lines. An available-resource index does not establish that selected rules were read.
|
|
18
23
|
|
|
19
24
|
### Stage 1 — Language (iterate all rules)
|
|
20
25
|
|
|
@@ -33,44 +38,26 @@ Read `clean-code.md` for the language-agnostic principles, then select language,
|
|
|
33
38
|
|---|---|
|
|
34
39
|
| [frameworks/node-server.md](frameworks/node-server.md) | `package.json` or its dependencies/scripts show server-side Node work (`express`, `fastify`, `nestjs`, server entrypoints, API routes, CLI services); or a touched file is a Node runtime module |
|
|
35
40
|
|
|
36
|
-
Node.js server work
|
|
41
|
+
For Node.js server work, load both JavaScript/TypeScript and Node server resources.
|
|
37
42
|
|
|
38
43
|
### Stage 3 — Architecture (iterate all rules)
|
|
39
44
|
|
|
45
|
+
Declared architecture takes precedence over layout signals. `hexagonal` selects the resource below; `layered` applies its dependency-direction invariant without selecting that resource; explicit `none` selects no architecture overlay. Only an absent or `undeclared` style uses layout detection.
|
|
46
|
+
|
|
40
47
|
| Resource | Include when any condition matches |
|
|
41
48
|
|---|---|
|
|
42
|
-
| [architectures/hexagonal.md](architectures/hexagonal.md) | ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
|
|
43
|
-
|
|
44
|
-
If a layout looks hexagonal but is non-standard, ask one question — *"does this project follow ports-and-adapters? where is the domain?"* — and record the answer. Architecture overlays default to none when no rule matches.
|
|
45
|
-
|
|
46
|
-
If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code — do not invent a default.
|
|
49
|
+
| [architectures/hexagonal.md](architectures/hexagonal.md) | the project explicitly declares hexagonal architecture; or ports-and-adapters / hexagonal signals: `domain/` + `ports/` + `adapters/` (or `core/` + `infrastructure/` + `application/`), `*.port.*` files, NestJS hex split, or `abstract class` files at a domain boundary |
|
|
47
50
|
|
|
48
|
-
|
|
51
|
+
For an undeclared style with a non-standard layout that looks hexagonal, ask once which architecture and domain boundary apply, and record the answer. Undeclared overlays default to none when no rule matches.
|
|
49
52
|
|
|
50
|
-
|
|
51
|
-
- [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone + one identifier one meaning per file), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
|
|
52
|
-
- [ ] **Mutation and state boundaries** (`clean-code.md`): decide on the direct identifier, not a status/flag proxy; capture before-state in one snapshot ahead of the mutating boundary; update only this work's owned fields on an existing row; re-read state before calling a zero-affected-rows write success or failure; put priority-between-inputs in a named domain function; keep error messages to what was observed.
|
|
53
|
-
- [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process or acts on its behalf: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; new entry points enforce the project's operation-specific access policy, including shared, administrative, and explicitly public access where applicable; protect secrets and limit personal-data disclosure as specified in `clean-code.md`, including authorized data responses and credential issuance; no eval or unsafe deserialization of input.
|
|
54
|
-
- [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change and project rules permit it. Record the exact waived behavior or check and its unverified coverage. That waiver applies to the corresponding branch-test, branch-deletion, and resource-bound checks in this pack; it does not waive unrelated checks, weaken existing tests, or establish verified coverage.
|
|
55
|
-
- [ ] **Function changes reuse tests first:** before changing a function, search its behavior and callers and read candidate tests. If a behavior test exists, strengthen it in place; if it already verifies the changed contract, run and retain it. Add a test only when that behavior has no existing test, preferring an existing file. Record the function, reused test location, or uncovered outcome that justifies a new test. Do not generate one test per function, helper, or branch, or expand model/provider/task-type combinations without distinct outcomes. This is checked in the completion self-check and code review, not by a test-count target.
|
|
56
|
-
- [ ] **Existing tests surveyed (run this before planning any new test):** for every surface this change touches, `grep -rln` the candidate test files, list their test names, then READ the bodies of the ones that could overlap. A list of names does not tell you what a test asserts, and behavioural overlap does not collide on names — treat a clean name search as unfinished, not as a clear result. Record per surface: `extend <path:line>` / `new (nothing covers <behaviour>)` / `retire <path:line> (behaviour moved to <where>)`. A new test or test file with no survey line is unfinished work. The survey may change the design — moving the seam so existing tests keep passing beats adding parallel ones. Carry out a `retire` verdict in the same commit, on behavioural grounds only: the behaviour it asserted is gone, or a new test asserts it more strongly through the same seam. "Looks similar" / "touches the same file" is not grounds; without grounds the test stays, because a silent coverage loss costs more than one extra test.
|
|
57
|
-
- [ ] **Testing discipline:** apply the recorded testing waiver only to its stated scope. For tests written or edited, the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each unwaived branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
|
|
58
|
-
- [ ] **Third-party wrapper (when this change wraps a library call):** the wrapper adds behaviour the library does not already provide — read the installed library source before keeping a recovery branch — no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
|
|
59
|
-
- [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`, no changed domain file importing outward (ORM / framework / adapters / services), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory — record it with the port sketch; blocking when the project declares `architecture.style = hexagonal` in `.okstra/project.json` — fix before write, never record-and-pass).
|
|
60
|
-
- [ ] **Existing code searched — by capability, not by name:** `grep` the identifier you are about to add AND the behaviour it performs (call sites, domain literals, error strings, the shape of the data it returns). A capability that already exists under a different name is the duplication this check exists to catch, and an identifier grep alone never finds it — name-level uniqueness is not evidence of absence. Record per new unit: the search terms used, the nearest existing implementation found, and the verdict `extend <path:line>` / `new (nothing covers <behaviour>)`. No survey line, no new unit.
|
|
61
|
-
- [ ] Project conventions checked: `.editorconfig`, `CONTRIBUTING.md`, formatter config (`.prettierrc`, `rustfmt.toml`, `ktlint`, `google-java-format`, etc.). **Project rules override this resource pack on conflict.**
|
|
53
|
+
If no Stage 1 language rule matches (an unlisted language), stop and ask the user for the canonical style guide before writing code.
|
|
62
54
|
|
|
63
|
-
##
|
|
55
|
+
## Applying criteria within the assignment
|
|
64
56
|
|
|
65
|
-
|
|
57
|
+
Read-only reviewers evaluate these standards against source and authorized execution evidence. Report violations and unavailable checks to the lead; do not repair source, run a writing formatter or perform authoring procedures. Execute only checks the assignment authorizes.
|
|
66
58
|
|
|
67
|
-
|
|
68
|
-
- [ ] **Stand-alone name test for exports:** for each exported identifier, look at its siblings — can a caller pick the right one from the names alone? If a comment must explain which to use, the name fails; encode the distinguishing fact in it (e.g., the input shape: `parseRows` vs `parseRowsFromFlatItems`).
|
|
69
|
-
- [ ] **Self-mock sweep:** for every test file you added or edited, `grep` it for the SUT-stubbing patterns of this language (full list in `languages/*.md` → "Self-mock signals to refuse") — e.g. `spyOn(sut`, `sut.<method> = jest.fn`, `spyk(sut`, `Mockito.spy(`, `@Spy` paired with `@InjectMocks`, `patch(`-ing the class under test, `mockall::mock!` of the unit itself, plus private-reach hacks (`(sut as any).`, `ReflectionTestUtils.invokeMethod(sut`). Any hit where the stubbed/replaced target **is the unit under test** — not an injected collaborator — is a refused self-mock: delete the stub and exercise the real method, or the test only proves its own wiring and survives even if the real implementation is deleted. Mocking injected collaborators at the boundary stays fine; this sweep targets only stubs on the SUT itself. If a method on the SUT feels too painful to leave real, that's a design signal (extract it to a collaborator), not a license to stub it. Enforced by `validators/detect_self_mock.py` (static) — **run by the implementation verifier, never by the author of the diff.** This sweep is the manual half and ends at your own reading; the detector run and its `qa/self-mock-*.json` sidecar are the verifier's duty (`prompts/profiles/_implementation-verifier.md` §"Self-mock detection"), and it is that sidecar's absence that BLOCKS at `validate-run.py` — on the verifier's report, not on your diff. Running the detector yourself does not pre-satisfy the gate: the sidecar is outside an executor attempt's `writePolicy.artifactPolicy.allowedPaths`, so writing it makes okstra's write audit close the attempt as `error` (`artifact-root change exceeds batch policy union`), and the verifier writes the same file again under its own duty.
|
|
70
|
-
- [ ] **No documented forks:** two deliberate variants of one capability must not survive as parallel implementations with a comment explaining the delta. Re-read both bodies and check the deltas are genuinely parametric: if they reduce to a few orthogonal options, collapse into one implementation taking explicit option parameters that encode them. If encoding the delta would take more than ~3 options, or add more branching than the duplication it removes, they are two capabilities — keep two implementations with distinct honest names and delete the "variant of" framing. Either way the comment-documented fork dies. "The divergence is documented" stays a refused rationalization, and a two-capabilities verdict must come from reading the bodies, not from reluctance to refactor.
|
|
59
|
+
Workers authorized to change source also read [authoring-checks.md](authoring-checks.md) before editing. For a frozen policy, select that resource from its archive with `--resource authoring-checks.md`. Older captures may retain those procedures in this overview; use their captured text without substituting installed files.
|
|
71
60
|
|
|
72
|
-
##
|
|
61
|
+
## Verification commands
|
|
73
62
|
|
|
74
|
-
-
|
|
75
|
-
- This preflight does **not** replace repo-local rules. Repo rules win on conflict.
|
|
76
|
-
- This preflight does **not** cover every language. If the target language is missing, stop and ask.
|
|
63
|
+
Select repository-configured formatting, lint, type and test commands appropriate to the changed behavior and contracts. Execution authority and full-check timing follow the assignment and repository procedure. Do not add tools, configuration or dependencies solely for this pack. Record unavailable or unconfigured checks as unverified with reasons. Command selection does not waive 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
|
-
"
|
|
6
|
+
"Judge every assigned census cell against the frozen policy, acceptance conditions and five quality outcomes."
|
|
7
7
|
],
|
|
8
8
|
"requiredConduct": [
|
|
9
|
-
"
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"Return one compact Coverage Verdicts table row per assigned target/group cell. Explicitly account for every shared-catalog rule ID under Checked, N/A with an inline applicability reason, or Findings with finding IDs. Share one literal inspected target-source path:line per row. Do not expand pack bullets into separate verdict rows, use all-checked claims, or mark unread rules checked.",
|
|
13
|
-
"Inspect before accounting: evaluate changed constructs against every applicable canonical clause, follow result mappings and the work done by existing callees, and identify findings before compressing the coverage table. Passing tests and linters do not establish conformance to every assigned rule."
|
|
9
|
+
"Read the frozen diff, whole target files and affected callers, callees, contracts and tests before producing verdicts. Specialty limits verdict ownership, not context reads. Read complete applicable rule clauses; do not clip their text or replace frozen policy with installed files.",
|
|
10
|
+
"Use shared execution evidence only when its head and inputs match. Inspect assertions, failure and boundary cases and self-mocking where assigned. Ask the lead for necessary additional execution; do not launch duplicate suites.",
|
|
11
|
+
"On follow-ups, inspect the selected correction range and its impact before accepting this slot's carry candidates under a matching comparison base and policy. Supporting context outside the supplied census creates no independent targets; full inspection means that census. Reopen contradicted conclusions, distinguish inspected from inherited cells, retain earlier finding dispositions separately, and use full inspection when the boundary is uncertain."
|
|
14
12
|
],
|
|
15
13
|
"decisionPrinciples": [
|
|
16
|
-
"
|
|
17
|
-
"
|
|
14
|
+
"Use demonstrated impact and likelihood to grade actionable findings. Follow documented policy rather than preference, trace shared decisions before claiming duplication, and recommend the smallest correction.",
|
|
15
|
+
"Passing tests, valid output accounting and correct current outputs do not establish all five quality outcomes or excuse an applicable design violation."
|
|
18
16
|
],
|
|
19
17
|
"authorityAndBoundaries": [
|
|
20
|
-
"
|
|
18
|
+
"Keep census membership, rule ownership and the frozen comparison range unchanged. Do not broaden the diff or redesign unrelated code."
|
|
21
19
|
],
|
|
22
20
|
"evidenceStandards": [
|
|
23
|
-
"Each finding
|
|
24
|
-
"
|
|
25
|
-
"For checked G2, G3 and G5 rules in general cells, the Evidence field includes source-cited clean observations after ::, keyed by rule ID. G2 traces dependency outcome meanings through diagnostic values; G3 identifies workload dimensions, downstream work and limits before that work; G5 names the applicable canonical clauses and observed conformance. Missing or unsupported inspection stays unaccounted instead of clean."
|
|
21
|
+
"Each finding identifies its cell, source evidence, assigned rule or behavior, consequence and feasible correction. An execution-error establishes a reachable state, expected outcome and wrong result. A design-violation establishes an applicable rule and concrete design impact without requiring a runtime failure.",
|
|
22
|
+
"A clean verdict explains inspected evidence. For checked G2/G3/G5, preserve the calibration's source-cited observations after ::. Missing inspection or required execution stays unaccounted; unavailable performance bounds stay unverified."
|
|
26
23
|
],
|
|
27
24
|
"collaborationContract": [
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"Keep verdicts independent from other reviewers and the author. Do not echo a finding without verifying it, suppress a unique defect for consistency, or resolve cross-cell overlap by changing identifiers; return overlap information to the lead."
|
|
25
|
+
"Only the assigned review function belongs to this invocation. 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
|
-
"
|
|
29
|
+
"Return one grouped Coverage Verdicts row per assigned cell. Account for each expected rule exactly once under Checked, reasoned N/A or Findings, with the required target-source anchor and finding links. Preserve identifiers; no omitted rule is implicitly clean.",
|
|
30
|
+
"Report incomplete or blocked quality checks explicitly. Complete accounting authenticates the response shape, not the truth of its conclusions."
|
|
34
31
|
],
|
|
35
32
|
"prohibitions": [
|
|
36
|
-
"Do not
|
|
33
|
+
"Do not mark unread criteria checked or classify unsupported candidates as findings."
|
|
37
34
|
],
|
|
38
35
|
"blockedStateReporting": [
|
|
39
|
-
"
|
|
36
|
+
"Name each unevaluable cell, the missing source, policy, bound or execution evidence, the inspection attempted and the conclusion that remains unavailable."
|
|
40
37
|
]
|
|
41
38
|
}
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
"Maintain a fresh context from the execution session, and weigh the diff rather than the confidence of the narrative describing it. Do not ask the executor to supply the verdict, silently repair its work, or coordinate a passing conclusion; return actionable findings to the lead with enough evidence for a bounded correction."
|
|
22
22
|
],
|
|
23
23
|
"completionCriteria": [
|
|
24
|
+
"When Frozen Design Review is supplied, independently return every cell/rule verdict and structured finding against its exact base, head, policy and census fingerprints; missing accounting prevents acceptance. This is checked by design-review evidence validation, not by another worker's response.",
|
|
24
25
|
"Every assigned criterion and required check has an explicit pass, fail, or blocked disposition; material regressions and test-quality risks have been examined; and the overall verdict follows from the recorded evidence."
|
|
25
26
|
],
|
|
26
27
|
"prohibitions": [
|
|
@@ -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
|
|
21
|
-
- **Project policy projection:**
|
|
22
|
-
- **Declared architecture style — an authoritative Stage 3 input
|
|
23
|
-
- **Project review rule packs:**
|
|
24
|
-
- **Language-agnostic principles
|
|
25
|
-
- **
|
|
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.
|