okstra 0.231.0 → 0.232.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -3
- 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 +129 -2
- package/docs/architecture.md +11 -2
- 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/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- 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/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- 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/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- 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/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- 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 +12 -2
- 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 +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- 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_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -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/team.py +3 -1
- 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_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- 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 +17 -8
|
@@ -11,13 +11,15 @@ If unsure, ask the user once: *"Does this project use ports-and-adapters? What f
|
|
|
11
11
|
|
|
12
12
|
These rules are language-agnostic. The examples use TypeScript/Java-ish syntax; translate to Rust traits, Kotlin interfaces, etc., as needed.
|
|
13
13
|
|
|
14
|
+
Apply the policy precedence in `../overview.md`: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Once this overlay is selected, apply each rule's stated criteria and severity whether selection came from a declaration or layout signals. H5 alone keeps its undeclared-style advisory exception. Existing concrete dependencies or misplaced rules do not create an exception to an applicable architecture rule.
|
|
15
|
+
|
|
14
16
|
---
|
|
15
17
|
|
|
16
18
|
## Rule H1 — Ports stay thin
|
|
17
19
|
|
|
18
|
-
A port is the interface (or abstract class) at the domain/application boundary.
|
|
20
|
+
A port is the interface (or abstract class) at the domain/application boundary. It declares an operation's inputs, outputs, errors and domain-owned query specifications without implementing business decisions. Describing those behavioral contracts is part of the port's interface.
|
|
19
21
|
|
|
20
|
-
A port file's method body
|
|
22
|
+
A port file's executable method body does not implement:
|
|
21
23
|
|
|
22
24
|
- `if` statements that branch on domain state.
|
|
23
25
|
- Validation that throws or returns errors based on input shape.
|
|
@@ -53,36 +55,29 @@ Not a violation:
|
|
|
53
55
|
|
|
54
56
|
---
|
|
55
57
|
|
|
56
|
-
## Rule H2 — Adapters
|
|
57
|
-
|
|
58
|
-
Same principle as H1, on the adapter side. The adapter's job is to implement **just** the I/O — a SQL query, an HTTP call, a filesystem read. It is **not** the place to filter by domain state, branch on domain values, or compute business answers.
|
|
58
|
+
## Rule H2 — Adapters execute I/O; the domain owns business policy
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
An adapter translates a port operation into a SQL query, HTTP call, filesystem operation or other I/O. The domain owns the policy that determines eligibility, validity or a business outcome; the adapter may execute that policy's query specification efficiently without redefining its meaning.
|
|
61
61
|
|
|
62
|
-
|
|
63
|
-
- An `if` that rejects results based on a domain rule (*"skip if expired"*, *"exclude shared items"*).
|
|
64
|
-
- A method whose name encodes a business rule — `findValid*` / `findActive* `/ `findEligible*`. The adapter should fetch *things*; the caller (or the query itself) should apply the rule.
|
|
65
|
-
- Multiple joins and conditions assembled specifically to satisfy a compound domain rule — the adapter is answering a business question rather than offering a primitive fetch.
|
|
62
|
+
Inspect policy ownership and preservation of the port contract:
|
|
66
63
|
|
|
67
|
-
|
|
64
|
+
- A predicate or business calculation invented inside an adapter, with no domain-owned policy or defined port contract, hides the decision in infrastructure.
|
|
65
|
+
- An adapter that changes, omits or duplicates the policy's conditions can return a different business answer. Cite the governing policy and the differing condition.
|
|
66
|
+
- Post-fetch filtering merits inspection of its owner and cost. Technical row mapping or execution of a domain-owned specification is not inherently a policy violation.
|
|
68
67
|
|
|
69
|
-
-
|
|
70
|
-
- The method name itself encodes a domain rule that a reader cannot tell from the name alone.
|
|
68
|
+
SQL predicates, joins, aggregation, ordering and pagination may implement a domain-owned query specification at the storage boundary. Complexity or the number of conditions alone does not establish a misplaced rule. Check where the policy is defined and whether the query preserves its semantics.
|
|
71
69
|
|
|
72
|
-
A
|
|
70
|
+
A name such as `findValid*`, `findActive*` or `findEligible*` is valid when the port contract defines that term and identifies its governing policy or specification. An undefined or misleading term is a contract or naming problem, not proof that every business-oriented query belongs outside the adapter.
|
|
73
71
|
|
|
74
|
-
|
|
75
|
-
- Moving the predicate out would force an N+1 (the caller would have to fetch all rows and round-trip per row to decide which are valid).
|
|
72
|
+
Keep efficient execution near the data. Do not replace a policy-driven query with `findAll` plus in-memory filtering merely to move the predicate's syntax. Express the policy at the domain/application boundary and let the adapter translate it while preserving bounded work and avoiding N+1 calls.
|
|
76
73
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
Not a smell:
|
|
74
|
+
Examples of adapter responsibilities:
|
|
80
75
|
|
|
81
76
|
- Simple `WHERE` clauses for *data-shape* reasons (`WHERE user_id = ?`) — that's scoping the fetch, not a business rule.
|
|
82
77
|
- Pagination, ordering, basic projection.
|
|
83
78
|
- Mapping raw rows to domain objects — that's the adapter's translation job.
|
|
84
79
|
|
|
85
|
-
|
|
80
|
+
The review distinguishes changing business policy from translating it for a storage or transport system. A finding names the policy hidden or changed by the adapter and the concrete consequence; a complex query or a domain-oriented name alone is not evidence.
|
|
86
81
|
|
|
87
82
|
---
|
|
88
83
|
|
|
@@ -109,7 +104,7 @@ The test: **is this type/class a thing the business talks about, or is it plumbi
|
|
|
109
104
|
|
|
110
105
|
## Rule H4 — Dependency direction: the domain imports nothing outward
|
|
111
106
|
|
|
112
|
-
|
|
107
|
+
Dependencies point inward. A file under the domain folder imports only from the domain itself and from pure utility code. Read each changed domain file's imports and resolve their targets against the declared boundaries; apply the explicit repository instructions before judging an outward dependency.
|
|
113
108
|
|
|
114
109
|
Violations — any import of:
|
|
115
110
|
|
|
@@ -131,9 +126,9 @@ When the domain needs something the outside owns, invert it: declare the shape a
|
|
|
131
126
|
|
|
132
127
|
When a change adds or modifies a service's dependency on a concrete adapter — constructor injection of a repository class, or direct model / DB access from a service — that boundary should be a port the adapter implements, so the caller depends on shape rather than on infrastructure.
|
|
133
128
|
|
|
134
|
-
|
|
129
|
+
Inspect dependencies this change adds or modifies against the declared boundary and explicit repository instructions. An injection entirely outside the changed scope is not a new finding merely because it already uses a concrete class.
|
|
135
130
|
|
|
136
|
-
|
|
131
|
+
Existing concrete `*Repository` injections do not waive a declared hexagonal boundary. Apply the precedence in `../overview.md` and cite any explicit repository exception. Under a declared hexagonal style, fix a current violating dependency through a port before completion. Without that declaration, record the advisory and a proposed port with the method signatures it needs; do not require unrelated legacy cleanup.
|
|
137
132
|
|
|
138
133
|
---
|
|
139
134
|
|
|
@@ -145,7 +140,7 @@ Violations:
|
|
|
145
140
|
|
|
146
141
|
- An `if` / `else` chain over domain fields that decides an outcome — eligibility, validity, which branch of a business process runs.
|
|
147
142
|
- Arithmetic expressing a business formula: money, ranking, quota, date-based entitlement.
|
|
148
|
-
- A private service method
|
|
143
|
+
- A private service method that implements a business decision such as eligibility, a downgrade formula or status transition. Inspect its body and governing rule; a domain-oriented name alone is not a violation.
|
|
149
144
|
|
|
150
145
|
Not a violation:
|
|
151
146
|
|
|
@@ -155,21 +150,19 @@ Not a violation:
|
|
|
155
150
|
|
|
156
151
|
The test: **if this decision changed, would the change be described as a business rule change or as a plumbing change?** A business rule change that lands in a service is the violation — the rule is now invisible to the domain's own tests, and the next caller that needs it writes its own copy.
|
|
157
152
|
|
|
158
|
-
|
|
153
|
+
Grade an established H6 violation by `clean-code.md` "Finding evidence and grading". A substantial embedded rule, such as money, permissions or a state machine, is a current blocking finding even when layout signals selected this overlay. Current blocking findings are fixed before completion, subject to the explicit repository instructions.
|
|
159
154
|
|
|
160
155
|
---
|
|
161
156
|
|
|
162
|
-
**
|
|
163
|
-
|
|
164
|
-
Severity: advisory in a project that has not declared `architecture.style = hexagonal` — a direction-of-travel rule there, not a correctness gate, so it never blocks on its own. Under that declaration it is blocking: the injection is fixed before the write.
|
|
157
|
+
**Conflict resolution.** The precedence in `../overview.md` applies to every rule in this overlay, including H4 and H5. A surrounding code pattern alone cannot clear an explicit architecture violation. Cite an explicit repository instruction when it overrides a common-pack rule; record an unresolved conflict instead of treating it as a clean result. Boundary interpretation and grading are self-check and review judgments, not a guarantee from import scanning alone.
|
|
165
158
|
|
|
166
159
|
---
|
|
167
160
|
|
|
168
161
|
## Quick checklist before declaring a port/adapter change complete
|
|
169
162
|
|
|
170
163
|
- [ ] No `if` / `.filter` / validation / business math inside any port body.
|
|
171
|
-
- [ ]
|
|
172
|
-
- [ ]
|
|
164
|
+
- [ ] The domain owns business policy; adapter queries and any post-fetch processing preserve that policy and the port contract without redefining it.
|
|
165
|
+
- [ ] Domain-oriented adapter names identify a policy defined by the port contract; query complexity or the name alone is not a violation.
|
|
173
166
|
- [ ] Every entity, value object, domain enum, and domain error is declared under `domain/`.
|
|
174
167
|
- [ ] Port files only declare shape and `import` domain types — they don't *define* them.
|
|
175
168
|
- [ ] No changed domain file imports an ORM, a framework, or anything under adapters / infrastructure / services.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Authoring checks
|
|
2
|
+
|
|
3
|
+
These execution procedures apply only to the worker authorized to change project source. Read-only reviewers evaluate the shared criteria and report findings; this resource grants no write authority. Enforcement is author self-check and code review unless a referenced rule names an automated gate.
|
|
4
|
+
|
|
5
|
+
## Mandatory pre-write checks (every language)
|
|
6
|
+
|
|
7
|
+
- [ ] Read project instructions, configured conventions and every selected resource for this turn. Apply the shared [quality outcomes](clean-code.md#five-simultaneous-quality-outcomes) before editing.
|
|
8
|
+
- [ ] Before adding a unit, search identifiers, behavior, callers, domain literals, error strings and returned-data shapes; read the candidates. Record search terms, nearest implementation and `extend <path:line>` or `new (nothing covers <behavior>)`. Name-only uniqueness does not establish absence; missing survey evidence leaves the addition unfinished.
|
|
9
|
+
- [ ] **Tests planned:** identify retained or extended tests and uncovered outcomes under [Testing discipline](clean-code.md#testing-discipline) and [test reuse](clean-code.md#reuse-tests-before-adding-coverage). Record any permitted waiver and its unverified scope there.
|
|
10
|
+
- [ ] Apply the detailed checks in `clean-code.md`, including mutation/state, security, testing, third-party wrappers and failure paths where applicable.
|
|
11
|
+
- [ ] If the hexagonal overlay is selected, apply its H1–H6 criteria and stated exceptions under the policy precedence in `overview.md`.
|
|
12
|
+
|
|
13
|
+
## Completion sweep (before declaring a multi-file change done)
|
|
14
|
+
|
|
15
|
+
- [ ] Review the combined change for shared decisions and exported-name distinctions using `clean-code.md`'s DRY and naming checks, not only per-file checks.
|
|
16
|
+
- [ ] Manually inspect changed tests using the selected language's self-mock signals and `clean-code.md`'s testing criteria. Distinguish the tested unit from injected collaborators. In implementation runs, `validators/detect_self_mock.py` execution and its result files belong to the verifier designated by "Self-mock detection"; authors perform this manual sweep only. `validate-run.py` checks the result.
|
|
17
|
+
- [ ] Run the authorized repository commands selected under [Verification commands](overview.md#verification-commands). Report results, unresolved findings, waivers and unavailable checks without claiming unverified coverage.
|