opdev 0.7.0a2__py3-none-any.whl

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 (42) hide show
  1. opdev/__init__.py +1 -0
  2. opdev/__main__.py +3 -0
  3. opdev/checks.py +300 -0
  4. opdev/cli.py +459 -0
  5. opdev/commands.py +76 -0
  6. opdev/config.py +278 -0
  7. opdev/document_catalog.py +107 -0
  8. opdev/document_review.py +115 -0
  9. opdev/documents.py +415 -0
  10. opdev/errors.py +5 -0
  11. opdev/files.py +82 -0
  12. opdev/init.py +87 -0
  13. opdev/junit.py +99 -0
  14. opdev/output.py +141 -0
  15. opdev/process.py +145 -0
  16. opdev/providers/__init__.py +1 -0
  17. opdev/providers/gitlab.py +374 -0
  18. opdev/publication.py +209 -0
  19. opdev/reports.py +512 -0
  20. opdev/requirements.py +642 -0
  21. opdev/resources/reports/report.css +158 -0
  22. opdev/resources/reports/report.html +27 -0
  23. opdev/resources/reports/report.js +110 -0
  24. opdev/resources/skills/opdev/SKILL.md +190 -0
  25. opdev/resources/skills/opdev/references/adoption.md +144 -0
  26. opdev/resources/skills/opdev/references/design.md +141 -0
  27. opdev/resources/skills/opdev/references/development.md +294 -0
  28. opdev/resources/skills/opdev/references/engineering.md +206 -0
  29. opdev/resources/skills/opdev/references/planning.md +101 -0
  30. opdev/resources/skills/opdev/references/publication.md +34 -0
  31. opdev/resources/templates/AGENTS.md +7 -0
  32. opdev/resources/templates/CLAUDE.md +6 -0
  33. opdev/resources/templates/guidance.md +36 -0
  34. opdev/snapshot.py +484 -0
  35. opdev/tracking.py +224 -0
  36. opdev/verification.py +234 -0
  37. opdev/version.py +45 -0
  38. opdev-0.7.0a2.dist-info/METADATA +99 -0
  39. opdev-0.7.0a2.dist-info/RECORD +42 -0
  40. opdev-0.7.0a2.dist-info/WHEEL +4 -0
  41. opdev-0.7.0a2.dist-info/entry_points.txt +3 -0
  42. opdev-0.7.0a2.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,141 @@
1
+ # Understand and agree the design
2
+
3
+ Read the relevant fixed-catalog project documents and recover prior
4
+ acceptance before choosing a discovery question. Separate settled facts, current
5
+ scope, accepted later work and actual open choices.
6
+
7
+ When product direction is unresolved, ask open questions about the developer's
8
+ ideas, intended users, problem, outcomes and boundaries. Do not present your
9
+ assumptions as requirements or restrict discovery to your preferred solutions.
10
+
11
+ When product direction is accepted, begin with a brief recap of the actual actions
12
+ in the accepted current slice. Ask **how those actions should work** at the next
13
+ unresolved interface or technical boundary, not which features the product should
14
+ contain. Do not add suggested capabilities to that question or mix accepted later
15
+ work into it. A feature addition or reopening is a separate explicit proposal,
16
+ only when relevant to the developer's request. If a request conflicts with an
17
+ accepted decision, name the conflict and ask whether to reopen that decision.
18
+ Keep unaffected decisions settled; no new questionnaire or decision file.
19
+
20
+ Ask the relevant question now, including in response to "what next?"; do not merely
21
+ list a future discussion. Group related choices when useful and explain material
22
+ tradeoffs. Research significant unfamiliar choices with primary sources; a small
23
+ factual edit does not need a research project.
24
+
25
+ Work through these decision boundaries, preserving approvals already given:
26
+
27
+ 1. **Product:** write substantive design.md describing the problem, users, outcomes,
28
+ scope and exclusions. Obtain acceptance of the abstract product direction.
29
+ 2. **Interface:** establish user stories, interactions, inputs/outputs, important
30
+ failure cases and accessibility appropriate to the product. Write interface.md
31
+ and obtain acceptance of that contract; CLI, API and library interfaces count.
32
+ 3. **Technical:** ask about the developer's stack preferences and constraints, then
33
+ recommend the implementation approach, dependencies, formatter, linter, tests,
34
+ CI and relevant standards. Write the mandatory technical stack, architecture,
35
+ standards and verification files, plus justified selected optional roles. Obtain
36
+ acceptance of that substantive technical contract as one boundary; separate
37
+ owners do not add approval stages.
38
+
39
+ Apply the shared [coding practices](engineering.md#coding-practices). In the
40
+ technical owners, record the project's language conventions, meaningful module
41
+ boundaries, error-handling approach and chosen tools. Architecture.md records durable
42
+ architectural decisions, constraints and rationale. Source owns concrete structure;
43
+ native configuration owns executable restrictions. Apply
44
+ [architecture content review](engineering.md#architecture-content-review) and
45
+ [source organization](engineering.md#source-organization), including native
46
+ enforcement and its blind spots, without a parallel module inventory or universal
47
+ directory tree. Use [repository organization](engineering.md#repository-organization)
48
+ for artifact ownership, lifetime and native placement conventions. Keep exact rules
49
+ in native tool configuration and wire agreed checks into the required command inventory.
50
+ Reuse accepted choices; resolve missing or inapplicable tooling explicitly. Do not
51
+ copy the generic baseline into each project or invent a universal quality score.
52
+
53
+ Select the [complexity policy](engineering.md#complexity-policy) for each owned
54
+ language and code scope, including mixed-language projects. Prefer trustworthy
55
+ native tools already in use; explain limits and tradeoffs instead of adopting one
56
+ ecosystem's defaults universally. Resolve unavailable analysis with that policy's
57
+ practical review alternative. Do not install Python tools for unrelated languages
58
+ or create an OpDev complexity engine.
59
+
60
+ A preliminary stack preference is not approval of an unwritten technical contract.
61
+ Before seeking final technical approval, name the proposed tools and standards in
62
+ the substantive technical files; do not ask to approve choices that are still unspecified.
63
+
64
+ Use the fixed owners below. Approval concerns substantive content, not file creation
65
+ or a structural pass. Detailed plans are input: retain their accepted decisions,
66
+ identify unresolved matters and later divide implementation into useful slices.
67
+ Do not strip detail during document separation: inventory each decision, map it
68
+ to its owner, repair links and compare the saved meaning before removing an old
69
+ owned copy. Temporary comparison material stays outside the repository; Git
70
+ history supplies recovery. Do not invent decisions, retain competing archives,
71
+ or create ad hoc .opdev documents or subdirectories. Keep generic procedures
72
+ canonical in the skill and exact executable rules in native configuration.
73
+
74
+ Do not implement dependent work or request final roadmap approval while these
75
+ decisions remain unresolved. Explicit delegation to decide changes that boundary;
76
+ silence, broad product enthusiasm and agent-written labels do not. A user's specific
77
+ change request may already settle the affected design: do not repeat unrelated
78
+ approval stages or turn routine implementation choices into new ceremonies.
79
+
80
+ Once product, interface and technical decisions are substantive and accepted, move directly to
81
+ [planning](planning.md). Present the phased roadmap as the next part of the same
82
+ conversation. Do not start implementation until the relevant plan is authorized.
83
+
84
+ ## Document owners
85
+
86
+ The runtime catalog `opdev-documents/1` defines fixed paths and exact H2 sections.
87
+ All mandatory roles exist in every adopted project. Project configuration selects
88
+ optional roles with `documents: {layout: opdev-documents/1, optional: [...]}`;
89
+ omission selects the mandatory catalog without optional roles. Use only the named
90
+ optional roles when the project has relevant substantive decisions. Do not create
91
+ empty optional files in anticipation of later work. H3 and deeper subsections may
92
+ organize details within a required H2. Retain accepted detail instead of compressing
93
+ it to fit a template. An unresolved section must state the actual unresolved choice
94
+ and its effect; headings or generic placeholders do not make it substantive.
95
+
96
+ | Fixed file under .opdev | Required H2 sections | Owner |
97
+ | --- | --- | --- |
98
+ | guidance.md | Workflow; Project routes | Project instructions and selective routing to the canonical skill and project decisions |
99
+ | design.md | Problem and users; Outcomes; Scope and exclusions | Product direction |
100
+ | interface.md | Interactions; Inputs and outputs; Failures and compatibility | Observable behavior and compatibility |
101
+ | technical/stack.md | Languages and runtimes; Dependencies and tools; Platform constraints | Implementation tools and constraints |
102
+ | technical/architecture.md | Responsibilities; Source organization; Interfaces and dependencies; State and effects | Durable architectural decisions, constraints and rationale |
103
+ | technical/standards.md | Language conventions; Error handling; Complexity policy; Automated enforcement | Coding policy and native enforcement |
104
+ | technical/verification.md | Test strategy; Requirement verification; Focused checks and integration CI; Limitations | Durable test strategy, check boundaries and capability limitations; individual assertions belong in tests and managed test records |
105
+ | technical/data.md (optional) | Data ownership; Representations and invariants; Migration and recovery | Persistent/shared representations and lifecycle |
106
+ | technical/security.md (optional) | Trust boundaries; Access and sensitive data; Controls and limitations | Substantive security decisions |
107
+ | technical/operations.md (optional) | Deployment; Observability; Recovery; Maintenance | Operational ownership and procedures |
108
+ | technical/performance.md (optional) | Workloads and budgets; Measurement; Design constraints | Accepted performance constraints and measurement |
109
+ | technical/evaluation.md (optional) | Evaluation scope; Inputs and oracles; Execution procedure; Interpretation and limitations | Evaluation beyond ordinary deterministic tests |
110
+
111
+ `opdev documents validate [--format json]` reads required files/sections, local links
112
+ and unknown catalog entries. It neither writes nor executes project tools. Use it
113
+ for focused structural feedback after a document change. Full checks/publication
114
+ run the same cheap preflight before their configured commands; focused repair work
115
+ remains possible. A valid structure is not design acceptance, assertion adequacy
116
+ or proof that the prose is complete. Unknown or superseded files require deliberate
117
+ reconciliation; the checker never deletes, archives or migrates them. User-facing
118
+ documentation remains entirely developer-owned outside this internal catalog.
119
+
120
+ ### Document-only feedback boundary
121
+
122
+ For a migration, repair or accepted decision edit limited to catalog documents and
123
+ their selection, the feedback path is:
124
+
125
+ 1. Run `opdev documents validate` for the fixed catalog.
126
+ 2. Run the [shared handoff checkpoint](../SKILL.md#handoff-checkpoint) against the
127
+ starting commit and the accepted document owners.
128
+ 3. Review the actual diff for preserved decisions and report the observed results.
129
+ Technical edits still report `decision_review_required`; explain the substantive
130
+ review against the accepted change without calling it an automatic pass or asking
131
+ for the same approval again.
132
+
133
+ That completes document-only feedback. Do not append a configured check as a default
134
+ final step. Before adding one, inspect the configured command and its actual input
135
+ selection, identify which changed input it checks, and establish that execution is
136
+ within the request. With no affected input or explicit request, leave it unrun.
137
+ A name such as `docs` does not establish coverage: a README checker cannot validate
138
+ the internal catalog, and unchanged README input does not need rechecking for a
139
+ catalog migration. Existing generic instructions to run checks do not establish
140
+ that input relationship. Required integration checks remain at the later integration
141
+ boundary; this feedback path neither performs nor claims integration.
@@ -0,0 +1,294 @@
1
+ # Implement and verify the authorized slice
2
+
3
+ Use guidance and project.yaml to select the affected fixed document owner. For a
4
+ single-document correction, read that owner and the applicable procedure; load
5
+ another decision document only when the correction actually depends on it.
6
+ For implementation, read the current issue and accepted decisions controlling the
7
+ changed responsibilities. Inspect source and native configuration for concrete
8
+ structure. Selected optional roles are relevant only when their subject is affected.
9
+ Apply the [coding practices](engineering.md#coding-practices) for implementation and review.
10
+
11
+ ## Requirement and test records
12
+
13
+ ### Assertion adequacy
14
+
15
+ Query affected requirements and tests through `opdev requirement` and
16
+ `opdev requirement test`; establish missing enduring obligations and test intent
17
+ as the approved behavior becomes concrete. Keep direct mappings accurate; hierarchy
18
+ does not transfer verification. For each affected obligation, inspect the actual
19
+ assertions: concrete input, action, observable expected result, and relevant failure
20
+ paths. Explain why those assertions would fail if the promised behavior broke;
21
+ exercise a small deliberate defect for a critical guard when useful. Trace the actual
22
+ fixture state at each assertion: write one case then test it, or use distinct paths;
23
+ later setup must not overwrite an earlier case before it is exercised. Test
24
+ semantic validation with syntactically valid inputs: malformed JSON rejection does
25
+ not test a blank field's validation. Distinguish those failure paths explicitly.
26
+ A no-effect guarantee needs an assertion observing or forbidding the effect on
27
+ each demonstrated input path,
28
+ including its edge cases; checking a return value alone cannot prove it.
29
+ Trace the effect to its actual boundary before choosing a spy or stub: watching a
30
+ pure helper does not observe transport, filesystem or database access, even when
31
+ that helper's name sounds like an effect. A test name,
32
+ passing process, mapping or review checkbox is not that explanation. Record the
33
+ review in the existing issue/MR, not a new evidence file. Fix inadequate assertions
34
+ before linking their exact reported JUnit identities. Keep unavailable behavioral
35
+ or platform testing explicitly unverified; static packaging checks cannot replace it.
36
+
37
+ ### Managed record edits
38
+
39
+ Choose identity from the accepted obligation: independent added behavior gets a
40
+ separate requirement. Preserve unchanged requirement statements and links; do not
41
+ broaden them to absorb another capability. Reuse an ID only for an accepted revision
42
+ to that same obligation.
43
+
44
+ For new or changed tests, first use [assertion adequacy](#assertion-adequacy).
45
+ Base each `verifies` description on that named test's actual assertions, not the
46
+ whole suite. If coverage is split, register and directly link each needed test and
47
+ reconcile descriptions of the split/replaced tests. Check the final test bodies
48
+ against their individual descriptions before readback; another linked test cannot
49
+ make an overbroad description true.
50
+
51
+ Edit requirement and test records through `opdev requirement` and
52
+ `opdev requirement test`, including description-only changes; do not patch
53
+ requirements.json directly. Query the affected record, apply
54
+ only the intended fields with its `--if-match` revision, then read it back. For example:
55
+
56
+ ```console
57
+ opdev requirement test show TST-01 --requirements --format json
58
+ opdev requirement test update TST-01 --verifies "Rejects malformed input with the public error." --if-match REVISION --format json
59
+ opdev requirement test show TST-01 --requirements --format json
60
+ ```
61
+
62
+ Substitute the actual record ID, intended assertion and returned revision. Omitted
63
+ fields preserve selectors, locations and direct links. A stale revision means the
64
+ store changed: reread, preserve the intervening changes and reapply the still-valid
65
+ delta with the new revision. Do not drop the guard or overwrite from an old copy.
66
+ The CLI's write guards protect its operations, not arbitrary filesystem edits.
67
+
68
+ Registering a test with `opdev requirement test add` does not link it, even if its
69
+ ID matches a requirement. Use `opdev requirement link REQUIREMENT TEST`, then
70
+ `opdev requirement show REQUIREMENT --tests` and confirm the named test appears
71
+ before reporting the mapping complete.
72
+
73
+ ## Configured tools
74
+
75
+ Use `opdev commands` to discover configured purposes and CLI help for syntax.
76
+ Use build, test, lint, format or run only for the intended task; format --check
77
+ checks formatting while format applies edits. A missing purpose needs a deliberate
78
+ configuration choice, not guessed tool flags. Before editing native tool policy,
79
+ locate and read the configuration the selected command actually uses, including
80
+ hidden files, inherited settings and precedence. Ordinary listings may omit these.
81
+ Amend that controlling configuration; adding an ignored or lower-priority copy does
82
+ not enforce the policy. Inspect resolved settings with the tool when available and
83
+ within scope; otherwise verify its documented selection rules and state what remains
84
+ unexecuted. Don't bypass a failing configured check by running an easier replacement
85
+ or weakening the requirement.
86
+
87
+ ## Change brief and checkpoint
88
+
89
+ At the start of an authorized change, use the existing issue/MR description as the
90
+ brief. If tracking is unavailable or writes are outside scope, state the brief in
91
+ the conversation and say it is unsaved. For a small task, a few lines suffice:
92
+
93
+ - **Change:** accepted behavior/decision delta and its authority in the conversation.
94
+ - **Preserve:** unaffected guarantees, real tracker identities, completed and later work.
95
+ - **Owners:** affected document roles, or none; references to controlling decisions.
96
+ - **Demonstrate:** concrete input, action, expected observation and relevant failure cases.
97
+ - **Boundary:** focused checks, remaining verification and the authorized stopping point.
98
+
99
+ Set the owners before editing, from the accepted decision delta rather than the
100
+ files mentioning the feature. For each technical owner, identify the actual accepted
101
+ technical decision being changed, or the explicitly requested repair/migration of
102
+ that document. A document-only repair preserves accepted meanings; it does not
103
+ require inventing a new technical decision. Without either authority, leave that
104
+ owner out and keep its content unchanged. A new channel name, delivery date or milestone does not by
105
+ itself change architecture. Do not discover the task's authority from the diff you
106
+ already wrote. This brief reuses existing acceptance; it is not a new approval step.
107
+
108
+ Reuse approved issue scope rather than starting another planning stage. Do not
109
+ copy whole designs, add .opdev files or make a second backlog. Keep these same
110
+ obligations through correction and handoff; update only the accepted delta.
111
+
112
+ Run the [shared handoff checkpoint](../SKILL.md#handoff-checkpoint) against the
113
+ recorded starting commit, with only the owners justified by this brief. It lists
114
+ all changed paths and flags catalog owners outside the selection; a selected owner
115
+ is not approval. Inspect the actual diff, including new/untracked files, for changed
116
+ meaning, test assertions, unexpected effects and the accepted scope. It cannot
117
+ judge prose, infer consent or certify implementation correctness. Use
118
+ `opdev documents validate` after catalog edits for structural checks separately.
119
+
120
+ Technical changes always remain `decision_review_required`, even when their owner
121
+ is selected. There is no flag to approve them or make that result clear. For an
122
+ incidental refresh, restore only your change and inspect again. For an already
123
+ accepted technical change or explicit document repair/migration, quote the actual
124
+ developer instruction authorizing that specific delta and explain how the diff
125
+ matches it. An agent's own "accepted" label or broad instruction to implement a
126
+ feature or update affected designs is insufficient. If the only accepted delta is
127
+ product/interface behavior, keep that content with those owners and restore the
128
+ incidental technical edit. Report the automated finding and this grounded review
129
+ separately; neither the quote nor owner selection authenticates consent. Reuse
130
+ actual prior approval without asking again, and never call the checkpoint passed.
131
+ An unresolved technical decision still needs the developer.
132
+
133
+ Resolve findings before claiming completion. Revert only your own incidental
134
+ refreshes when no decision changed, preserving preexisting/concurrent user edits.
135
+ Restoring file content need not write Git metadata: if the index is protected,
136
+ read the known base with Git and restore only the owned content through ordinary
137
+ file edits. Preserve its bytes when no change is intended. Do not change protections
138
+ or repeatedly retry an index-writing command; report an unresolved restoration honestly.
139
+ Do not widen the owner selection merely to make the checkpoint clear. A real
140
+ unapproved decision needs the developer's decision; an unauthorized external effect
141
+ cannot be undone by a clean diff or rewritten response. With no usable Git base,
142
+ state scope inspection unavailable and compare against the actual starting inputs
143
+ manually; never fabricate a clean checkpoint. Ignored artifacts still need the
144
+ repository-organization review and the full catalog structural check.
145
+
146
+ ## Focused results and handoffs
147
+
148
+ Execute selected feedback checks through `opdev check --only ID --format json`
149
+ (repeat `--only` for multiple IDs), or the corresponding OpDev purpose command.
150
+ Read command status and exit information from that result; never execute its
151
+ underlying argv directly to confirm an exit code or compensate for missing JUnit.
152
+ Configured execution and result interpretation belong to the same CLI operation.
153
+
154
+ Review the brief, actual diff, current check output and relevant tracker readback
155
+ as one completion checkpoint. Use the shared [invariants](../SKILL.md#preserve-scope)
156
+ for authority and completion. One agent may perform this distinct review pass;
157
+ no mandatory reviewer hierarchy or extra approval stage is introduced.
158
+
159
+ When review finds a defect, identify its location and observable consequence,
160
+ correct within scope, then repeat the affected checks and checkpoint. For a missing
161
+ no-effect assertion, identify the actual effect boundary, not a similarly named
162
+ pure helper. Preserve original failed observations. Corrections retain the brief's
163
+ preserved/later work and prior valid results; do not replace the task with the latest
164
+ finding. A response-only correction needs no unchanged code rerun. An inability to
165
+ access a tool is not a code defect. Substantive scope violations remain failures.
166
+
167
+ Build the handoff from observed facts: command outcome, named-test evidence and
168
+ requirement verdict with their respective IDs; exact observable output; actual
169
+ saved tracker changes or explicitly unsaved proposals; outstanding limits. Keep
170
+ expected demonstrations separate from observed execution. Check every claim
171
+ against the brief and results, including integration/completion and release authority.
172
+ Use [Changed-feature handoff](#changed-feature-handoff) for accepted feature changes.
173
+ Reuse the brief's exact examples after a correction. Changing an assertion or its
174
+ effect observer does not change the approved output; update only the corrected
175
+ observation or failure witness, not the example's input or expected value.
176
+
177
+ Full `opdev check` and `opdev publish` require valid document structure, successful
178
+ required commands and complete active requirement verification. Focused checks
179
+ report the same catalog gaps without expanding execution scope. Missing mappings,
180
+ selectors, unexecuted or failing cases remain explicit blockers to full verification;
181
+ a focused command may pass while its mapping verdict remains incomplete.
182
+ Command success is not named-test proof, assertion adequacy, consent or remote CI.
183
+ A structural pass cannot establish document meaning or approval.
184
+
185
+ Reuse relevant focused results for unchanged inputs. Rerun for changed source,
186
+ tests, command configuration or runtime, stale/failed evidence or concrete
187
+ uncertainty; explain why in the existing work record. Mapping-only edits require
188
+ mapping inspection, not another identical execution. Saved reports describe their
189
+ captured inputs, never qualification of changed source. Required integration and
190
+ publication checks still run at their normal boundary. Reporting adds no check stage.
191
+
192
+ Keep findings in the existing work item/handoff unless a separate follow-up is
193
+ warranted. Use native Git/MR tooling and the shared protected integration rule;
194
+ missing protection blocks integration, not independent local work. Review changed,
195
+ added and untracked paths with [repository organization](engineering.md#repository-organization),
196
+ assertions and failure handling with [coding practices](engineering.md#coding-practices), and saved
197
+ configuration/decisions against the actual claimed result. No permanent evidence ledger.
198
+
199
+ ## Continue and finish
200
+
201
+ Recover the current brief and tracker state after interruption; do not restart
202
+ accepted design or discard later milestones. Apply the shared
203
+ [continuation and completion invariants](../SKILL.md#preserve-scope). Until verified
204
+ integration and required post-merge checks, report "implemented; integration pending"
205
+ and keep current tracker work open/updated, including unsaved proposals. A proposed
206
+ future closure must explicitly depend on that verification. Preserve completed history.
207
+
208
+ After the authorized boundary passes, update tracker status and safely retire only
209
+ owned completed branches/worktrees. Preserve shared, dirty, protected or newer work;
210
+ use the host's managed-worktree archive where applicable. Never mass-delete by name.
211
+ Publication remains a separate [procedure](publication.md) requiring its own authority.
212
+
213
+ ## Changing direction
214
+
215
+ 1. **Identify and settle the delta.** Inspect affected decisions, partial code,
216
+ requirement assertions and tracker scope. Distinguish addition, replacement,
217
+ removal and deferral. Explain effects on interfaces, data, guarantees and milestones.
218
+ A precise request may already authorize execution; ask only unresolved consequential
219
+ choices and continue independent work. Do not choose removal versus deferral yourself.
220
+ 2. **Update the existing brief.** Name affected owners under the shared invariants;
221
+ preserve unaffected decisions. Retain accepted later work and completed history by
222
+ real tracker identity. Reconcile accepted document changes before implementation.
223
+ Delivery timing belongs in tracking, never architecture. No new approval journal.
224
+ 3. **Reconcile obligations and work.** Apply [managed record edits](#managed-record-edits)
225
+ for requirement identity, assertion intent and direct mappings. Revise actual
226
+ assertions without weakening unrelated guarantees.
227
+ Draft the observable demonstration now in the affected issue, or the unsaved brief.
228
+ Name each affected record's disposition: preserved, updated, deferred, cancelled,
229
+ or previously completed. Replacement completion does not complete deferred work.
230
+ Give every deferred issue a destination and correct ordering: use a valid existing
231
+ milestone or propose a later one by title, outcome, input/action/expected-result
232
+ demonstration, dependencies and membership. A prerequisite is not the destination.
233
+ Do not make current replacement work depend on its deferred successor. Apply the
234
+ [planning procedure](planning.md) to new milestones; identify any unresolved choice.
235
+ Reuse a bounded issue only while its accepted outcome fits; otherwise create/propose
236
+ a separate replacement within authority. No invented IDs or renamed completed work
237
+ that hides an unfinished outcome.
238
+ 4. **Implement and review.** Remove or adapt superseded work within scope after resolving
239
+ data loss/compatibility choices. Use focused verification and the
240
+ [change checkpoint](#change-brief-and-checkpoint). Git and tracker writes are separate:
241
+ use revisions/readback and reconcile actual state after interruption. Confirm the
242
+ implementation, assertions and affected contracts agree; no incidental document
243
+ refreshes. Report unavailable/out-of-scope tracker writes explicitly.
244
+ 5. **Hand off against the same brief.** Carry forward the demonstration, preserved and
245
+ deferred work, observed verification and precise saved/unsaved tracker changes below.
246
+ If a decision is pending, end with its real question instead of inventing acceptance.
247
+ Do not append full CI just to finish a feedback response.
248
+
249
+ ### Changed-feature handoff
250
+
251
+ Fill these four fields with actual facts; replace every placeholder. The demonstration
252
+ must show specific input and visible output, not "normal/empty cases tested" or a
253
+ function signature. Carry the same text into the affected tracker description or
254
+ unsaved proposal. Use the changed slice if no milestone is affected.
255
+ For exact text or payloads, copy the expected literal from the accepted contract
256
+ and verify the assertion matches it. Quote or serialize it separately from explanatory
257
+ prose so spaces, empty values, newlines and escapes remain visible. For example,
258
+ `Expected: "label: " (one trailing space)` is precise; `returns label:` is not.
259
+ Do not paraphrase a previously correct literal when correcting another part of the
260
+ handoff. A passing implementation cannot silently redefine its expected result.
261
+ Fill verification from the [shared handoff checkpoint](../SKILL.md#handoff-checkpoint)
262
+ observation as well as the configured results, retaining any unavailable boundary.
263
+
264
+ ```text
265
+ Demonstration: <concrete input/action> -> Expected: <quoted/serialized value or concrete visible outcome>; <edge input/action> -> Expected: <value/outcome>. Effects: <required or forbidden effects>.
266
+ Preserved/deferred: <unchanged promises, later work and cancellations>.
267
+ Verification: <observed documents review status against START_COMMIT and actual diff review; configured checks and remaining gaps>.
268
+ Tracker: <saved changes with read-back kind, ID, exact title and links OR exact unsaved changes and reason>.
269
+ ```
270
+
271
+ Apply [tracker identities](#tracker-identities) to every existing-record proposal,
272
+ including an offline handoff. Match each proposed disposition to the original kind,
273
+ ID and title before sending or applying it; completed history is not the current work.
274
+
275
+ Do not invent provider IDs: refer to new unsaved records by title. Separate an expected
276
+ demonstration from observed execution. This is response/description text, not a new
277
+ file, local state or an extra verification stage.
278
+
279
+ ### Tracker identities
280
+
281
+ Identify an existing record by its kind, ID and exact title from the relevant
282
+ tracker result, keeping explanation separate from its name. Phase, milestone and
283
+ issue numbers can overlap; never borrow a parent's or another record's title.
284
+ Reuse available observations; refresh them when missing, stale or contradicted.
285
+ An update preview reports the current identity beside `changes`; a proposed title
286
+ is not the current title. State a rename separately within the accepted scope,
287
+ then use the saved title returned by readback. Renaming needs no separate approval
288
+ when already covered by the developer's instructions.
289
+ Resolve membership from tracker reads and read back the saved association. For
290
+ new unsaved proposals, use the destination milestone's proposed title until creation
291
+ returns its real ID. Do not present an unsaved rename as an observed fact.
292
+
293
+ Keep current decisions in their fixed document owners and work/rationale in the
294
+ tracker. Do not add a change-request engine, local backlog or approval journal.
@@ -0,0 +1,206 @@
1
+ # Engineering review
2
+
3
+ Load the relevant section for changed code, artifact placement or native tool policy.
4
+ Task authority, check scope and completion remain in the skill and development procedure.
5
+
6
+ ## Coding practices
7
+
8
+ Choose the simplest coherent design for the accepted requirements. Judge the
9
+ resulting system, not patch size. Before substantive implementation, inspect the
10
+ affected responsibilities and decide whether to extend, refactor or introduce a
11
+ boundary. Refactor when patching around the structure would duplicate domain rules,
12
+ spread implementation details, accumulate modes or couple unrelated changes.
13
+ Explain material choices in the existing issue/MR; no separate design ritual.
14
+
15
+ Internal refactoring needed for an approved feature is part of implementation,
16
+ without separate permission when accepted behavior and technical boundaries stay
17
+ intact. Resolve changes to public contracts, compatibility, stored data or major
18
+ architecture through the existing design process unless explicitly delegated.
19
+
20
+ Apply these rules with the language's idioms and accepted project conventions:
21
+
22
+ - Give cohesive behavior and domain rules clear ownership. Hide changeable details
23
+ behind useful interfaces. Separate effects from decision logic where that makes
24
+ behavior easier to understand or test; do not force a layer around every function.
25
+ - Justify abstractions by a present requirement, a real shared concept or a concrete
26
+ simplification. One consumer can justify an important boundary; do not wait for
27
+ three copies. Similar-looking code with different meanings may remain separate.
28
+ Avoid both speculative frameworks and repeated patches that obstruct needed change.
29
+ - Make names, control flow, inputs, outputs and failure contracts understandable.
30
+ Use useful types/schemas and validate external input at appropriate boundaries.
31
+ Comments explain constraints and reasons; public interfaces describe their use.
32
+ - Recover from errors deliberately or propagate useful context. Never disguise an
33
+ unexpected failure as success. Retry only with a bounded policy and safe semantics.
34
+ Make state/resource ownership and cleanup on failure or cancellation explicit;
35
+ choose bounded waits or cancellation appropriate to the operation.
36
+ - Test observable promises, important boundaries and failure paths. Add practical
37
+ regression tests for defects. Do not mock away the behavior being verified or
38
+ compute expected results with the same algorithm under test. Synchronize on
39
+ observable readiness, not guessed delays; retain and investigate flaky failures.
40
+ - Follow the accepted formatter, linter, compiler/type checks and relevant security
41
+ practices using configured commands. Use established safe facilities for parsing,
42
+ escaping, authentication and cryptography. Justify new dependencies by current
43
+ needs. A suppression must be narrow and explain its reason; never broadly disable
44
+ checks to obtain a pass.
45
+ - Keep changes focused, update affected contracts/tests/docs and remove obsolete
46
+ owned code when no supported contract needs it. Separate broad mechanical edits
47
+ from behavior changes. Add performance complexity for an identified constraint
48
+ or demonstrated benefit, not speculation.
49
+
50
+ ## Repository organization
51
+
52
+ Before adding or moving a file, identify its purpose, lifetime and responsible
53
+ capability or tool. Inspect relevant native configuration, accepted conventions
54
+ and a representative neighbor, then extend the existing owner or introduce a
55
+ cohesive one where needed. This is local placement judgment, not a repository-wide
56
+ discovery pass, metadata record or approval per file. Resolve a conflict with an
57
+ accepted decision through the existing design boundary; do not silently override it.
58
+
59
+ Use these placement rules without inventing mandatory directory names:
60
+
61
+ - Product code and shipped resources belong to the capability/package that uses
62
+ them, following native framework, package and resource discovery.
63
+ - Tests and fixtures follow the established test arrangement and the behavior they
64
+ verify. Co-location and separate test trees can both be appropriate.
65
+ - Reusable development automation belongs with existing tooling, or its sole
66
+ consumer where clearer. Deployment and operational files belong to the system
67
+ they configure. Native tools may require root or other special locations.
68
+ - User documentation follows the developer's organization; OpDev does not own it.
69
+ Agent-facing decisions use the fixed `.opdev` catalog. Work plans and progress
70
+ use the configured tracker, never local planning files or a tracker mirror.
71
+ - Build output and caches use configured output locations and normally remain
72
+ untracked. Temporary investigations and trial output use external scratch or an
73
+ appropriate ignored location. Intentionally versioned generated source, golden
74
+ fixtures and maintained examples remain valid when their consumer and, for
75
+ generated files, producer are clear; do not delete them merely as "generated."
76
+ When their inputs change, regenerate through that producer and review the result
77
+ under the project's native formatting/line-ending rules. Do not maintain a
78
+ hand-edited copy that the next generation would replace.
79
+
80
+ New top-level entries need a concrete native discovery, package or supporting
81
+ responsibility. Do not create competing scripts/tools/helpers collections for the
82
+ same purpose, empty future layers or a miscellaneous shared dumping ground. Names
83
+ such as common or utils are review signals, not forbidden words. Apply the existing
84
+ abstraction rules: one consumer may justify a real boundary. Preserve sound flat
85
+ projects; no universal src tree, path schema, depth limit or file quota is required.
86
+
87
+ At the existing completion review, inspect added, moved **and untracked** paths:
88
+ does each have an owner, do imports/test discovery/resource packaging still work,
89
+ is there a competing home or stale copy/reference, and did disposable output enter
90
+ maintained source? Check tracked files as well as ignore rules: adding .gitignore
91
+ does not untrack files. Remove only owned obsolete material within scope. Use
92
+ configured native checks for affected discovery, package contents and dependencies;
93
+ name/path checks are optional project choices and cannot prove semantic ownership.
94
+ No new generic OpDev tree analyzer, directory inventory or review stage is needed.
95
+
96
+ Record unusual placement rationale and concrete findings in the existing issue/MR.
97
+ Keep only durable reasons, accepted exceptions and enforcement limits in the fixed
98
+ technical owners; exact executable settings remain in native configuration. During
99
+ adoption, preserve sound organization and identify actual gaps. During feature work,
100
+ fix affected disorder when needed, without an automatic repository-wide reshuffle.
101
+ Consequential public package, storage or architectural changes retain the existing
102
+ approval boundary; ordinary placement and internal refactoring remain autonomous.
103
+
104
+ ## Source organization
105
+
106
+ Keep durable architectural decisions, constraints and their rationale in
107
+ technical/architecture.md. Source code owns concrete files, modules, interfaces
108
+ and dependencies; native tool configuration owns executable restrictions. Inspect
109
+ those authorities for the current task. Do not maintain a parallel module inventory,
110
+ directory tree, interface list or dependency graph in architecture.md or add an
111
+ OpDev-generated copy. Developer-owned user documentation remains outside this rule.
112
+ A small stateless project may remain in one file; no literal src directory or
113
+ universal feature-folder tree is required.
114
+
115
+ ### Architecture content review
116
+
117
+ Use the fixed sections for consequential decisions, their reasons and guarantees.
118
+ "Source organization" holds organizing principles, not a prescribed directory plan.
119
+ Review each paragraph: would moving, splitting or replacing internal implementation
120
+ require rewriting it while accepted behavior and constraints stayed unchanged?
121
+ If so, it is probably an implementation observation. Removing filenames or replacing
122
+ them with component names does not turn a module map or call sequence into a decision.
123
+
124
+ Keep real constraints and explain the consequence they prevent. For example, all
125
+ report formats sharing a verification verdict prevents contradictory results;
126
+ listing the parser, assembler and renderer in order merely describes current code.
127
+ Delete redundant observations, including algorithm mechanics and copied configuration
128
+ values. Link an existing authority when needed; do not relocate the inventory into
129
+ another document. Genuine material owned by another fixed role belongs there once.
130
+ Do not remove deliberately accepted structural constraints without authority to
131
+ reconcile them, or invent rationale for an unexplained choice.
132
+
133
+ Review the saved result for both preserved decisions and removed implementation
134
+ inventory, including paraphrased inventory. Structure validation, sentence retention
135
+ and absence of paths cannot establish this. Use the existing review and issue/MR;
136
+ no new approval stage or prose-classification engine. Internal refactoring needs no
137
+ document update when these decisions stay intact. During adoption, infer supported
138
+ intent from source and tools and resolve consequential uncertainty.
139
+
140
+ Start with the existing owner. Refactor it or introduce a useful boundary when
141
+ otherwise extending it would duplicate policy, import another owner's private
142
+ internals, scatter a responsibility, reverse or cycle dependencies, accumulate
143
+ miscellaneous shared code or make callers depend on hidden details. Use names and
144
+ interfaces that expose intent. Do not move lines merely to shrink a file, impose
145
+ one module per function or create empty future layers. Internal refactors needed
146
+ for accepted work are authorized within that scope; consequential public-contract,
147
+ storage-ownership and major-architecture changes use the existing design boundary.
148
+
149
+ Use the language/compiler's native module and visibility rules first, then a
150
+ suitable existing native dependency checker where it enforces an accepted rule.
151
+ Keep exact executable settings in that tool's controlling configuration and wire
152
+ it through existing project commands. Explain what it enforces and leaves open in
153
+ technical/standards.md. Mixed-language projects may need different mechanisms;
154
+ OpDev adds no universal tool, metric, dependency graph engine or source-tree rule.
155
+ Validate a newly added or changed boundary check with an isolated permitted example
156
+ and a forbidden example through the configured native check. Reuse adequate
157
+ existing probes. A written rule or successful all-allowed run alone does not prove
158
+ that the forbidden dependency is rejected.
159
+
160
+ Where native enforcement is absent or incomplete, the same coding agent reviews
161
+ the changed owners and affected callers for actual coupling, hidden knowledge,
162
+ duplicate decisions, dependency direction and state/effect ownership. Record a
163
+ concrete consequence and proportionate remedy for findings in the existing issue/MR.
164
+ Keep the blind spot explicit; do not claim automatic enforcement, invent another
165
+ reviewer requirement or install unrelated language tools. Passing checks cannot
166
+ certify cohesion or maintainability.
167
+
168
+ ## Complexity policy
169
+
170
+ Keep one concise, actionable policy in technical/standards.md for each
171
+ owned language/scope. Name the native analyzer and relevant version/documentation,
172
+ what unit it measures and how its metric counts decisions, the exact limit boundary
173
+ (for example, whether the limit itself passes), and whether findings warn or fail.
174
+ Keep executable settings in native configuration and existing commands/checks.
175
+ After editing command wiring, validate the saved project with `opdev commands`;
176
+ it parses configuration without running the native tools. Repair parsing errors
177
+ before claiming the configuration ready, even when tool execution is out of scope.
178
+ Explain what a maintainer should do with a finding; a tool name and number alone
179
+ are not an actionable policy. Different tools need not share semantics or limits.
180
+
181
+ Follow the project's accepted complexity policy in technical/standards.md and
182
+ native tools. Complexity findings should lead to clearer responsibilities, control
183
+ flow or domain boundaries while preserving behavior and useful tests. Do not game
184
+ a score by splitting arbitrary fragments into helpers, moving branches into opaque
185
+ data or expressions, or hiding violations with broad exclusions or weaker limits.
186
+ A narrow exception needs a concrete reason, scope and review in the existing
187
+ issue/MR; existing code is not automatically grandfathered. Warning-count baselines
188
+ and suppressions do not prove that complexity has not increased. Review the whole
189
+ edited exempted function, including unchanged lines; claim automatic changed-function
190
+ gating only when the selected tool actually supplies it. When an analyzer is missing
191
+ or unsuitable, state the uncovered scope. The **same coding agent** reviews the
192
+ changed code; this does not request a person, human approval or another reviewer.
193
+ Preserve an existing project requirement for human review, but do not introduce one
194
+ as the fallback for a missing analyzer. Do not claim automatic enforcement or install
195
+ unrelated tooling. Define
196
+ that review concretely: inspect the maintained changed unit and affected boundaries
197
+ for mixed responsibilities, nested decisions and error paths; simplify control flow
198
+ or separate a coherent responsibility where this improves understanding. Preserve
199
+ observable behavior and its tests. Retain existing syntax/type checks, but do not
200
+ call them complexity analysis or claim that writing the policy completed a review.
201
+
202
+ Do not impose universal function/file limits, coverage percentages, architectural
203
+ patterns or duplication bans. Tool metrics and counting semantics differ; passing
204
+ a numerical gate cannot certify maintainability. A finding must name the code,
205
+ consequence and proportionate remedy. Concrete defects and accepted-rule violations
206
+ need resolution; personal preference alone does not block completion. Apply the existing project review process.