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,158 @@
1
+ :root {
2
+ color-scheme: dark; font: 13px/1.45 system-ui, sans-serif;
3
+ --bg: #0e151d; --panel: #111c26; --head: #182630; --line: #2a3b47;
4
+ --text: #d9e3ec; --muted: #a5b4c2; --accent: #e5ad81; --pass: #9bd5b6; --gap: #f1d28a;
5
+ color: var(--text); background: var(--bg);
6
+ }
7
+ * { box-sizing: border-box; }
8
+ body { margin: 0; }
9
+ main { padding: 0 20px 28px; }
10
+ h1, h2, h3, p { margin: 0; }
11
+ h1 { font-size: 16px; font-weight: 600; letter-spacing: -.3px; }
12
+ h2 { font-size: 16px; } h3 { font-size: 13px; }
13
+ p { margin: 10px 0; }
14
+ a { color: var(--accent); text-underline-offset: 3px; }
15
+ button, input, select { font: inherit; background: var(--panel); color: var(--text); border: 1px solid var(--line); border-radius: 2px; padding: 5px 9px; }
16
+ button { cursor: pointer; font-size: 11px; }
17
+ button:hover, button[aria-pressed=true] { color: var(--accent); border-color: var(--accent); }
18
+ button:disabled { cursor: default; opacity: .6; }
19
+ :focus-visible { outline: 2px solid #f3caa9; outline-offset: 2px; }
20
+ [hidden] { display: none !important; }
21
+ .skip { position: absolute; top: -80px; left: 20px; padding: 8px; background: var(--panel); z-index: 10; }
22
+ .skip:focus { top: 8px; }
23
+ .report-header, .identity, .overview, .totals, .headline, nav, .section-heading, .tree-controls, .tree-footer, .test-heading { display: flex; align-items: center; gap: 16px; }
24
+ .report-header { justify-content: space-between; border-top: 2px solid var(--accent); border-bottom: 1px solid var(--line); padding: 14px 0 12px; }
25
+ .identity h1 { border-left: 1px solid var(--line); padding-left: 16px; }
26
+ .wordmark { font: 700 18px ui-monospace, monospace; letter-spacing: -1px; white-space: nowrap; }
27
+ .wordmark b { color: var(--accent); }
28
+ .run-time { font-size: 11px; color: var(--muted); }
29
+ .overview { justify-content: space-between; padding: 10px 0; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
30
+ .totals { gap: 24px; flex-wrap: wrap; }
31
+ .totals > span, .headline { font-size: 12px; color: var(--muted); }
32
+ .totals strong { font: 600 21px ui-monospace, monospace; color: var(--text); margin-right: 6px; }
33
+ .badge { display: inline-block; font-size: 11px; }
34
+ .badge.pass::before, .result.pass::before { content: '✓ '; }
35
+ .badge.gap::before, .result.gap::before { content: '◇ '; }
36
+ .pass { color: var(--pass); } .gap { color: var(--gap); }
37
+ .scope { margin: 7px 0 4px; font-size: 12px; }
38
+ .limits { color: var(--muted); font-size: 11px; }
39
+ summary { cursor: pointer; }
40
+ .limits p { max-width: 100ch; }
41
+ nav { padding: 9px 0; border-bottom: 1px solid var(--line); font-size: 12px; }
42
+ nav button { margin-left: auto; }
43
+ section { scroll-margin-top: 12px; }
44
+ #commands, #run { margin-top: 28px; }
45
+ .section-heading { justify-content: space-between; padding: 9px 0; }
46
+ .section-heading > span { font-size: 11px; color: var(--muted); }
47
+ .warning, #blockers { border-left: 3px solid var(--gap); padding: 12px 16px; background: #302719; color: #f5ddab; margin: 12px 0; overflow-wrap: anywhere; }
48
+ #blockers h2 { font-size: 15px; } #blockers ul { margin: 8px 0 0; padding-left: 18px; }
49
+ #filters { display: flex; align-items: end; flex-wrap: wrap; gap: 8px; margin-bottom: 10px; }
50
+ #filters label { display: block; font-size: 10px; color: var(--muted); margin-bottom: 3px; }
51
+ #filters input, #filters select { font-size: 12px; width: 100%; min-width: 0; }
52
+ .search-field { flex: 1; min-width: 200px; max-width: 420px; }
53
+ .tree-controls { margin-left: auto; gap: 6px; }
54
+ .tree-wrap { overflow: auto; max-height: max(260px, calc(100dvh - 270px)); border: 1px solid var(--line); background: var(--panel); scrollbar-color: #586775 var(--bg); }
55
+ #requirements:has(#inspector:not([hidden])) .tree-wrap { max-height: max(220px, calc(100dvh - 520px)); }
56
+ table { border-collapse: separate; border-spacing: 0; width: 100%; text-align: left; font-size: 12px; }
57
+ .tree { table-layout: fixed; min-width: 760px; }
58
+ .id-column { width: 162px; } .count-column { width: 96px; } .result-column { width: 168px; } .state-column { width: 82px; }
59
+ th { background: var(--head); color: var(--muted); font: 10px ui-monospace, monospace; text-transform: uppercase; letter-spacing: .4px; padding: 7px 10px; border-bottom: 1px solid var(--line); }
60
+ .tree thead { position: sticky; top: 0; z-index: 2; }
61
+ .tree th:nth-child(3) { text-align: right; }
62
+ .tree th span { font-size: 9px; text-transform: none; letter-spacing: 0; }
63
+ td { padding: 8px 10px; border-bottom: 1px solid var(--line); overflow-wrap: anywhere; vertical-align: top; }
64
+ .requirement td { padding: 0 10px; height: 28px; vertical-align: middle; border-bottom-color: #22323e; }
65
+ .requirement.root td { height: 31px; background: var(--head); border-top: 1px solid var(--line); font-weight: 600; }
66
+ .requirement:hover td { background: #202e38; }
67
+ .requirement.selected td { background: #322a27; }
68
+ .requirement.selected td:first-child { box-shadow: inset 3px 0 var(--accent); }
69
+ .id-cell { position: sticky; left: 0; z-index: 1; background: var(--panel); border-right: 1px solid var(--line); }
70
+ .tree th:first-child { position: sticky; left: 0; z-index: 3; border-right: 1px solid var(--line); }
71
+ .id-content { display: flex; gap: 6px; align-items: center; padding-left: min(calc(var(--depth) * 12px), 48px); min-height: 28px; }
72
+ .req-id { font: 11px ui-monospace, monospace; color: var(--muted); overflow-wrap: anywhere; }
73
+ .root .req-id { color: var(--accent); }
74
+ .branch { border: 0; background: none; padding: 0; width: 16px; flex-shrink: 0; color: var(--accent); }
75
+ .leaf { width: 16px; height: 28px; flex-shrink: 0; position: relative; }
76
+ .leaf::before { content: ''; position: absolute; left: 6px; top: 0; bottom: 0; border-left: 1px solid #586775; }
77
+ .leaf::after { content: ''; position: absolute; top: 14px; left: 6px; width: 8px; border-top: 1px solid #586775; }
78
+ .root .leaf::before, .root .leaf::after { display: none; }
79
+ .obligation summary { padding: 4px 0; font-size: 13px; }
80
+ .enhanced .obligation summary { display: flex; gap: 8px; align-items: center; list-style: none; }
81
+ .enhanced .obligation summary::-webkit-details-marker { display: none; }
82
+ .enhanced .obligation .req-body { display: none; }
83
+ .enhanced:not(.wrap) .statement { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
84
+ .statement { min-width: 0; }
85
+ .context-label { display: none; font-size: 10px; color: var(--muted); font-weight: normal; white-space: nowrap; }
86
+ .context .context-label { display: inline; }
87
+ .direct-count { text-align: right; font: 11px ui-monospace, monospace; }
88
+ .result { font-size: 11px; font-weight: normal; }
89
+ .lifecycle { color: var(--muted); font: 10px ui-monospace, monospace; }
90
+ .requirement[data-state=proposed] .lifecycle { color: var(--gap); }
91
+ .req-body { padding: 12px 0; font-weight: normal; }
92
+ .req-body p { margin: 8px 0; }
93
+ .req-body .full-statement { font-size: 13px; }
94
+ .tests { margin: 10px 0 0; padding: 0; list-style: none; }
95
+ .tests li + li { margin-top: 12px; border-top: 1px solid var(--line); padding-top: 12px; }
96
+ .test-heading { justify-content: space-between; flex-wrap: wrap; font: 11px ui-monospace, monospace; }
97
+ .tests p { color: var(--muted); font-size: 12px; }
98
+ dl { display: grid; grid-template-columns: 100px minmax(0, 1fr); gap: 4px 14px; font-size: 12px; margin: 10px 0; }
99
+ dt { color: var(--muted); } dd { margin: 0; overflow-wrap: anywhere; }
100
+ #inspector { border: 1px solid var(--line); border-top: 2px solid var(--accent); margin-top: 8px; background: var(--panel); max-height: 250px; overflow: auto; padding: 0 16px 12px; }
101
+ #inspector .section-heading { position: sticky; top: 0; background: var(--panel); }
102
+ #inspector-heading { font: 13px ui-monospace, monospace; color: var(--accent); }
103
+ #inspector .req-body { padding-top: 0; }
104
+ .tree-footer { justify-content: space-between; gap: 10px; color: var(--muted); font-size: 11px; }
105
+ .tree-footer p { margin: 7px 0; }
106
+ #empty { padding: 24px; color: var(--muted); text-align: center; }
107
+ .scroll-hint { display: none; font-size: 11px; color: var(--muted); }
108
+ .muted, footer { color: var(--muted); font-size: 12px; }
109
+ .table-wrap { overflow: auto; border: 1px solid var(--line); }
110
+ .table-wrap table { min-width: 640px; }
111
+ .cases { padding: 12px 0; border-bottom: 1px solid var(--line); overflow-wrap: anywhere; }
112
+ .cases summary { color: var(--accent); }
113
+ .cases li { margin: 8px 0; }
114
+ code { font-family: ui-monospace, monospace; font-size: 11px; overflow-wrap: anywhere; }
115
+ .metadata { grid-template-columns: 200px minmax(0, 1fr); }
116
+ footer { padding-top: 16px; border-top: 1px solid var(--line); margin-top: 28px; }
117
+ @media (max-width: 800px) {
118
+ main { padding: 0 12px 20px; }
119
+ .report-header { flex-wrap: wrap; gap: 8px; }
120
+ .identity { gap: 9px; } .identity h1 { padding-left: 9px; font-size: 15px; }
121
+ .run-time { overflow-wrap: anywhere; font-size: 10px; }
122
+ .totals { gap: 9px 16px; } .totals strong { font-size: 18px; }
123
+ .headline { gap: 9px; } .overview { gap: 8px; }
124
+ nav { flex-wrap: wrap; gap: 10px; } nav button { margin-left: 0; }
125
+ .search-field { max-width: none; flex-basis: 100%; }
126
+ .tree-controls { margin-left: 0; flex-wrap: wrap; }
127
+ .scroll-hint { display: block; }
128
+ .tree-wrap { max-height: 65vh; }
129
+ .tree { min-width: 680px; }
130
+ .id-column { width: 148px; } .result-column { width: 150px; } .state-column { width: 74px; } .count-column { width: 84px; }
131
+ .tree-footer { display: block; }
132
+ .metadata { grid-template-columns: 1fr; gap: 3px; } .metadata dd { margin-bottom: 8px; }
133
+ #inspector { max-height: 65vh; }
134
+ }
135
+ @media print {
136
+ :root { color-scheme: light; color: #111; background: white; --text: #111; --muted: #333; --accent: #333; --pass: #111; --gap: #111; --panel: white; --head: white; --line: #aaa; }
137
+ main { margin: 0; padding: 0; }
138
+ nav, #filters, .tree-footer, #empty, .skip, #inspector, .branch, .leaf, .context-label, .scroll-hint { display: none !important; }
139
+ .tree-wrap, #requirements:has(#inspector:not([hidden])) .tree-wrap { overflow: visible; max-height: none; border: 0; }
140
+ .tree, .tree tbody { display: block; min-width: 0; }
141
+ .tree thead { display: none; }
142
+ .requirement, .requirement[hidden] { display: block !important; border-top: 1px solid #aaa; margin-top: 14px; }
143
+ .requirement td { display: block; height: auto !important; padding: 0; border: 0; background: white !important; box-shadow: none !important; }
144
+ .requirement .id-cell { position: static; }
145
+ .id-content { padding-left: 0; }
146
+ .requirement .direct-count, .requirement .lifecycle, .requirement td:has(>.result) { display: inline-block; margin-right: 14px; text-align: left; }
147
+ .direct-count::before { content: 'Direct tests passed/mapped: '; }
148
+ .lifecycle::before { content: 'State: '; }
149
+ details::details-content { display: block !important; content-visibility: visible !important; }
150
+ details > :not(summary) { display: block !important; }
151
+ .enhanced:not(.wrap) .statement { white-space: normal; overflow: visible; }
152
+ .obligation summary { display: block !important; }
153
+ .full-statement { display: none; }
154
+ .table-wrap { overflow: visible; } .table-wrap table { min-width: 0; font-size: 10px; }
155
+ .table-wrap th, .table-wrap td { padding: 4px; }
156
+ h2, h3, summary { break-after: avoid; }
157
+ .warning, #blockers { background: white; color: #111; border-color: #333; }
158
+ }
@@ -0,0 +1,27 @@
1
+ <!doctype html>
2
+ <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
3
+ <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; script-src 'sha256-$digest'; base-uri 'none'; form-action 'none'">
4
+ <title>OpDev verification report — $run_id</title><style>$css</style></head>
5
+ <body><a class="skip" href="#requirements">Skip to requirements</a><main>
6
+ <header class="report-header"><div class="identity"><span class="wordmark">opdev <b>/</b></span><h1>Requirement verification</h1></div><span class="run-time">Saved run finished <time>$finished</time></span></header>
7
+ <div class="overview"><div class="totals"><span><strong>$passed/$active</strong> active requirements passed</span><span><strong>$incomplete</strong> incomplete</span><span><strong>$required_passed/$required_total</strong> required commands passed</span></div><div class="headline">$outcome<span>$operation · $scope</span></div></div>
8
+ <p class="scope">Run outcome: $run_outcome. $scope_text</p>$warning
9
+ <details class="limits"><summary>Unsigned saved observation · Source content was not captured · No release authorization</summary><p>$limits</p></details>
10
+ <nav aria-label="Report sections"><a href="#requirements">Requirements</a><a href="#commands">Commands</a><a href="#run">Run details</a><button id="print" hidden>Print complete report</button></nav>$blockers
11
+ <section id="requirements" aria-labelledby="requirements-heading"><div class="section-heading"><h2 id="requirements-heading">Requirement tree</h2><span>$total recorded · direct results only</span></div>
12
+ <form id="filters" hidden role="search"><div class="search-field"><label for="search">Find requirement or test</label><input type="search" id="search" placeholder="ID, statement or test name"></div>
13
+ <div><label for="state">State</label><select id="state"><option value="all">All states</option><option value="active">Active</option><option value="proposed">Proposed</option><option value="retired">Retired</option></select></div>
14
+ <div><label for="result">Result</label><select id="result"><option value="all">All results</option><option value="gaps">Verification gaps</option><option value="passed">Mapped tests passed</option></select></div><button type="reset">Clear filters</button>
15
+ <div class="tree-controls"><button type="button" id="expand">Expand all</button><button type="button" id="collapse">Collapse all</button><button type="button" id="wrap" aria-pressed="false">Wrap statements</button></div></form>
16
+ <p class="scroll-hint">Scroll the table sideways to compare direct tests, results and lifecycle; requirement IDs stay visible.</p>
17
+ <div class="tree-wrap" tabindex="0" role="region" aria-label="Requirement hierarchy, scroll to inspect more records"><table class="tree"><colgroup><col class="id-column"><col><col class="count-column"><col class="result-column"><col class="state-column"></colgroup><thead><tr><th>Requirement tree</th><th>Obligation · inspect for details</th><th>Direct tests<br><span>passed / mapped</span></th><th>Direct result</th><th>Lifecycle</th></tr></thead><tbody id="requirements-list">$tree</tbody></table><p id="empty" $empty_hidden>$empty_text</p></div>
18
+ <section id="inspector" aria-labelledby="inspector-heading" hidden><div class="section-heading"><h2 id="inspector-heading" tabindex="-1"></h2><button id="close-inspector" type="button">Close details · Esc</button></div><div id="inspector-content"></div></section>
19
+ <div class="tree-footer"><p id="count" aria-live="polite">$total requirements listed.</p><p>Parents use their own tests. No inherited verification. Proposed and retired states remain separate.</p></div>
20
+ <noscript><p>All requirements and their native expandable details are available above. Search, branch controls and the detail panel need JavaScript; reading and printing do not.</p></noscript></section>
21
+ <section id="commands" aria-labelledby="commands-heading"><h2 id="commands-heading">Commands</h2>
22
+ <p>All declared commands are listed; only selected commands were requested.</p>
23
+ <div class="table-wrap" tabindex="0" role="region" aria-label="Command outcomes, scroll horizontally if needed"><table><thead><tr><th>Command</th><th>Purpose</th><th>Required</th><th>Selected</th><th>Outcome</th><th>Exit</th><th>Seconds</th></tr></thead><tbody>$commands</tbody></table></div>$cases</section>
24
+ <section id="run" aria-labelledby="run-heading"><h2 id="run-heading">Run details</h2><dl class="metadata">$details</dl>
25
+ <p class="muted">Fingerprints identify inputs; they do not authenticate this record. Source links and absolute test locations are omitted. Command arguments, logs and environment values are not included.</p></section>
26
+ <footer>One run. No checks run when this report is opened. No upload or release authorized.</footer>
27
+ </main><script>$js</script></body></html>
@@ -0,0 +1,110 @@
1
+ "use strict";
2
+ const byId = id => document.getElementById(id);
3
+ const form = byId("filters"), search = byId("search"), state = byId("state"), result = byId("result");
4
+ const rows = [...document.querySelectorAll(".requirement")];
5
+ const byRowId = new Map(rows.map(row => [row.id, row]));
6
+ const collapsed = new Set(rows.filter(row => row.querySelector(".branch")).map(row => row.id));
7
+ // Authored content remains escaped, server-rendered text. Never parse it as markup.
8
+ const texts = new Map(rows.map(row => [row, row.textContent.toLocaleLowerCase()]));
9
+ const ancestors = new Map(rows.map(row => {
10
+ const parents = [];
11
+ let parent = byRowId.get(row.dataset.parent);
12
+ while (parent) { parents.push(parent); parent = byRowId.get(parent.dataset.parent); }
13
+ return [row, parents];
14
+ }));
15
+ let selected = null, trigger = null;
16
+ function closeInspector(restoreFocus = true) {
17
+ byId("inspector").hidden = true;
18
+ byId("inspector-content").replaceChildren();
19
+ if (selected) selected.classList.remove("selected");
20
+ selected = null;
21
+ if (trigger) {
22
+ trigger.setAttribute("aria-expanded", "false");
23
+ trigger.parentElement.open = false;
24
+ }
25
+ if (restoreFocus && trigger && !trigger.closest("[hidden]")) trigger.focus();
26
+ }
27
+ function inspect(row, summary) {
28
+ closeInspector(false);
29
+ selected = row; trigger = summary;
30
+ summary.setAttribute("aria-expanded", "true");
31
+ summary.parentElement.open = true;
32
+ row.classList.add("selected");
33
+ byId("inspector-heading").textContent = `${row.dataset.key} · ${row.dataset.state}`;
34
+ // Leave the complete canonical body in place for no-JS reading and print.
35
+ byId("inspector-content").replaceChildren(row.querySelector(".req-body").cloneNode(true));
36
+ byId("inspector").hidden = false;
37
+ byId("inspector-heading").focus();
38
+ }
39
+ function filter() {
40
+ const query = search.value.trim().toLocaleLowerCase();
41
+ const filtering = query !== "" || state.value !== "all" || result.value !== "all";
42
+ const matches = new Set(rows.filter(row => texts.get(row).includes(query)
43
+ && (state.value === "all" || row.dataset.state === state.value)
44
+ && (result.value === "all" || (row.dataset.gap === "true") === (result.value === "gaps"))));
45
+ const shown = new Set(matches);
46
+ if (filtering) matches.forEach(row => ancestors.get(row).forEach(parent => shown.add(parent)));
47
+ let visible = 0;
48
+ rows.forEach(row => {
49
+ row.hidden = filtering ? !shown.has(row) : ancestors.get(row).some(parent => collapsed.has(parent.id));
50
+ if (!row.hidden) visible++;
51
+ row.classList.toggle("context", filtering && shown.has(row) && !matches.has(row));
52
+ const branch = row.querySelector(".branch");
53
+ if (branch) {
54
+ const open = filtering || !collapsed.has(row.id);
55
+ branch.textContent = open ? "▾" : "▸";
56
+ branch.setAttribute("aria-expanded", String(open));
57
+ branch.setAttribute("aria-label", `${open ? "Collapse" : "Expand"} ${row.dataset.key} descendants`);
58
+ branch.disabled = filtering;
59
+ }
60
+ });
61
+ byId("count").textContent = filtering
62
+ ? `${matches.size} matches + ${visible - matches.size} parents for context · ${rows.length} recorded.`
63
+ : `${visible} of ${rows.length} requirements listed.`;
64
+ byId("empty").hidden = visible !== 0;
65
+ if (selected && selected.hidden) closeInspector(false);
66
+ }
67
+ document.documentElement.classList.add("enhanced");
68
+ rows.forEach(row => {
69
+ const branch = row.querySelector(".branch");
70
+ if (branch) {
71
+ branch.hidden = false;
72
+ branch.addEventListener("click", () => {
73
+ collapsed.has(row.id) ? collapsed.delete(row.id) : collapsed.add(row.id);
74
+ filter();
75
+ });
76
+ }
77
+ const summary = row.querySelector("summary");
78
+ summary.setAttribute("role", "button");
79
+ summary.setAttribute("aria-controls", "inspector");
80
+ summary.setAttribute("aria-expanded", "false");
81
+ summary.addEventListener("click", event => { event.preventDefault(); inspect(row, summary); });
82
+ });
83
+ form.hidden = false;
84
+ form.addEventListener("input", () => { closeInspector(false); filter(); });
85
+ form.addEventListener("submit", event => event.preventDefault());
86
+ form.addEventListener("reset", () => {
87
+ collapsed.clear(); closeInspector(false);
88
+ setTimeout(filter, 0);
89
+ });
90
+ byId("expand").addEventListener("click", () => { collapsed.clear(); filter(); });
91
+ byId("collapse").addEventListener("click", () => {
92
+ rows.filter(row => row.querySelector(".branch")).forEach(row => collapsed.add(row.id)); filter();
93
+ });
94
+ byId("wrap").addEventListener("click", event => {
95
+ event.currentTarget.setAttribute("aria-pressed", String(document.documentElement.classList.toggle("wrap")));
96
+ });
97
+ byId("close-inspector").addEventListener("click", () => closeInspector());
98
+ document.addEventListener("keydown", event => {
99
+ if (event.key === "Escape" && !byId("inspector").hidden) closeInspector();
100
+ });
101
+ const print = byId("print");
102
+ print.hidden = false;
103
+ print.addEventListener("click", () => window.print());
104
+ let closed = [];
105
+ window.addEventListener("beforeprint", () => {
106
+ closed = [...document.querySelectorAll("details:not([open])")];
107
+ closed.forEach(item => { item.open = true; });
108
+ });
109
+ window.addEventListener("afterprint", () => { closed.forEach(item => { item.open = false; }); });
110
+ filter();
@@ -0,0 +1,190 @@
1
+ ---
2
+ name: opdev
3
+ description: Use OpDev in initialized software projects or for setup and explicit adoption. Offer adoption before substantive development elsewhere; routine pulls, status and dev-server work do not activate the workflow.
4
+ ---
5
+
6
+ # OpDev
7
+
8
+ ## Enter at the right point
9
+
10
+ Inspect only enough to identify the actual project and request. Loading this skill
11
+ does not authorize adoption. For substantive development in an uninitialized
12
+ project, offer OpDev before research or implementation and wait for acceptance.
13
+ If declined or unanswered, continue the requested work without OpDev. Routine
14
+ pulls, status, dev servers and external infrastructure need no offer or ceremony.
15
+ Present adoption as optional, never a prerequisite to development. Ask about using
16
+ the workflow; do not bundle that consent with permission to scaffold or implement.
17
+
18
+ In initialized projects, read `.opdev/guidance.md` and `.opdev/project.yaml` once
19
+ per fresh context or relevant change. Project decisions remain authoritative;
20
+ this package supplies reusable procedures, not permission to replace those decisions.
21
+ Malformed configuration is an error, not permission to initialize again.
22
+ The runtime owns a fixed document catalog under `.opdev`; project.yaml selects
23
+ optional technical roles, never arbitrary paths. The [design procedure](references/design.md#document-owners)
24
+ explains the owners and required sections. Start from guidance and configuration,
25
+ then read only the files and sections relevant to the current task. Open `.opdev`
26
+ paths directly: ordinary searches may hide them. Product decisions belong in
27
+ design.md, interface decisions in interface.md, and technical decisions with their
28
+ selected technical owner. A README is not a substitute. Unknown roles or files
29
+ need reconciliation, not an invented route or another discovery sweep.
30
+ The [scope invariants](#preserve-scope) determine which owners may change. Establish
31
+ the [change brief](references/development.md#change-brief-and-checkpoint) before
32
+ implementation and use the [handoff checkpoint](#handoff-checkpoint) before reporting
33
+ the result; these reuse existing tracking, not another file.
34
+ Do not extend or translate a file/function inventory into prose:
35
+ source and native configuration own concrete structure; architecture records only
36
+ durable decisions and rationale. An actual change to those decisions still needs
37
+ reconciliation through the design procedure.
38
+ After a catalog-document edit, run `opdev documents validate` for structural
39
+ feedback. Ad hoc heading/substring checks do not replace this built-in check;
40
+ review the diff separately for preserved meaning and approval.
41
+ For catalog-only migration or repair, use the [document-only feedback boundary](references/design.md#document-only-feedback-boundary).
42
+ Before selecting an additional configured check, inspect its actual input selection
43
+ and identify the changed input it covers. A name such as `docs` does not establish
44
+ that relationship. Follow the document-only feedback path when only the catalog changed.
45
+ Requirement/test records are CLI-managed data, including description-only edits.
46
+ Before writing them, read [managed records](references/development.md#managed-record-edits)
47
+ and use `opdev requirement` / `opdev requirement test`, not direct file patches.
48
+
49
+ Use the configuration already read as the capability inventory. If `tracking` is
50
+ absent, OpDev tracker operations are unavailable: do not probe phase/milestone/issue
51
+ commands or invent local tracker files. Use supplied records for proposals and state
52
+ what remains unsaved. Absence is a settled capability fact, not a cue to search the
53
+ checkout or plugin files for a hidden tracker. Inspect only relevant documents,
54
+ commands and records; once they answer the task, proceed instead of starting another
55
+ discovery sweep. Use help only for an operation needed now,
56
+ choosing it from observed CLI help rather than guessed status/roadmap/config verbs.
57
+ Reuse observations until relevant state changes or evidence contradicts them.
58
+ For test results, inspect the command's declared result format. With no
59
+ `results: junit`, there are no emitted JUnit identities to select: retain a null
60
+ selector and report named-test verification unavailable. Repeating the same command
61
+ or guessing a function name cannot supply the missing result capability.
62
+
63
+ ## Mandatory protected integration
64
+
65
+ Changes reach a project's integration branch only through its native merge/pull
66
+ request path with required CI passing. Never push directly to that branch, force
67
+ push it, or bypass its protections. The rule applies to main, master, develop or
68
+ any other chosen integration branch, for every developer, agent and automation.
69
+ Small fixes, documentation, adoption, upgrades and release/version changes are not
70
+ exceptions. Ordinary task or release approval does not waive this rule.
71
+
72
+ Check the actual destination ref before a push; the current local branch name is
73
+ not enough. Explicit refspecs, configured push defaults, mirror/all pushes and
74
+ publisher automation must not update an integration branch directly. Push only
75
+ work branches and use the protected merge path. Do not weaken protections to make
76
+ a blocked operation succeed. A requested exception is a conflict with OpDev's rule,
77
+ not a compliant alternative to record as approved.
78
+
79
+ Native provider settings enforce this boundary. Require and inspect them during
80
+ [adoption and upgrades](references/adoption.md#require-the-protected-merge-path),
81
+ and recheck them at integration or after relevant changes. Missing access or
82
+ protection leaves hosted adoption/integration incomplete; continue independent
83
+ local work. Local-only setup can proceed, but remote integration remains unverified
84
+ until a protected destination exists. The CLI does not intercept arbitrary Git
85
+ commands, and successful local checks do not prove provider enforcement.
86
+
87
+ ## Load only the current procedure
88
+
89
+ | Current need | Read |
90
+ | --- | --- |
91
+ | Install, adopt a new/existing project, or upgrade | [Adoption](references/adoption.md) |
92
+ | Discover needs or resolve a consequential design choice | [Design](references/design.md) |
93
+ | Approved designs, roadmap, milestone start or next-step planning | [Planning](references/planning.md) |
94
+ | Edit requirement/test metadata or recover a stale write | [Managed record edits](references/development.md#managed-record-edits) |
95
+ | Implement, review, verify, resume authorized work or clean up | [Development](references/development.md) |
96
+ | Add or move files, assets, fixtures or tooling | [Repository organization](references/engineering.md#repository-organization) |
97
+ | Place code, refactor boundaries or configure their enforcement | [Source organization](references/engineering.md#source-organization) |
98
+ | Choose or configure complexity checks, including configuration-only work | [Complexity policy](references/engineering.md#complexity-policy) |
99
+ | Interpret check results or finish a feedback handoff | [Focused results](references/development.md#focused-results-and-handoffs) |
100
+ | Add, replace or defer a feature during implementation | [Changing direction](references/development.md#changing-direction) |
101
+ | Explicitly requested release/publication | [Publication](references/publication.md) |
102
+
103
+ Follow a transition when it becomes relevant; do not preload every reference.
104
+ Interpreting a result is verification work even when no new code is requested;
105
+ read the relevant result procedure before prescribing a fix for a reported gap.
106
+ Resolve each procedure link from this skill's directory, not the working directory:
107
+ `references/development.md` is under the loaded skill, not `.opdev/references`.
108
+ Read the relevant procedure before its task, including a correction after review.
109
+ After locating a heading, read its section body. An empty search or a link label
110
+ is not that procedure; use the linked file's actual headings or read the file.
111
+ If the file is missing, locate the
112
+ actual linked package file; do not silently skip it or substitute CLI help.
113
+ Use CLI help for syntax rather than inventing commands. Before first CLI execution
114
+ in a fresh session or changed environment, compare `opdev version --format json`
115
+ from the developer-selected runtime with this package's [runtime identity](../../opdev-runtime.json).
116
+ Match implementation, version and workflow_sha256. The fingerprint identifies
117
+ packaged guidance, not tested code, approved decisions or release readiness.
118
+ For a source preview, use the explicitly supplied matching runtime and package.
119
+ Before reporting a supplied runtime missing, retry its exact supplied command/path;
120
+ a failed guessed or shortened path does not establish that it is unavailable.
121
+ Missing/mismatched tools need a setup resolution; no silent install or substitution.
122
+ Independent design discussion can continue without the CLI.
123
+
124
+ ## Preserve scope
125
+
126
+ These invariants apply to every procedure, including corrections:
127
+
128
+ - **Authority:** recover actual user instructions and accepted decisions from the
129
+ conversation and existing project/tracker records. A proposal, agent-written status
130
+ or selected CLI flag is not consent. Ask about unresolved consequential choices
131
+ unless explicitly delegated; make ordinary implementation choices autonomously.
132
+ - **Document ownership:** update only owners required by the accepted change.
133
+ Technical files remain unchanged unless a technical decision change or an explicit
134
+ technical-document repair/migration was accepted; an interface change or "update
135
+ affected designs" does not reopen them. A document repair preserves decision meanings. Product and
136
+ interface owners hold current feature behavior; architecture holds durable
137
+ constraints and reasons. Source and native configuration own concrete structure.
138
+ Tests and managed test records own individual assertion details; technical/verification.md
139
+ owns durable testing policy and capabilities. Fixing or adding an assertion is not a
140
+ technical-policy change or authorization to edit that document.
141
+ The document checkpoint never clears technical changes through owner selection;
142
+ it leaves decision review visible even for an already accepted technical edit.
143
+ - **Preservation:** retain unrelated edits, accepted later work, completed history,
144
+ requirement meaning and test guarantees. Reconcile affected records through their
145
+ guarded CLI; never fabricate identities or use a local tracker mirror.
146
+ - **Verification:** use relevant configured checks for feedback and all required
147
+ checks at integration. Select by actual inputs, not command names: `--only` on a
148
+ full-CI command still runs full CI. Do not copy configured argv into the shell or
149
+ substitute an easier check. Unavailable CLI/testing remains blocked/unverified.
150
+ - **Completion:** proposed, saved, implemented and verified are distinct. Current
151
+ tracker completion requires protected integration and required post-merge checks;
152
+ preserve previously completed history. Neither implementation nor completion
153
+ authorizes release, publication, deployment, tagging or consumer migration.
154
+ - **Continuation:** continue independent authorized work during narrow blockers.
155
+ A status question during ongoing work does not cancel it; a standalone status
156
+ question does not authorize implementation. Single agent remains the default.
157
+
158
+ ## Handoff checkpoint
159
+
160
+ Before editing a Git checkout, inspect preexisting changes and capture its starting
161
+ commit with Git's unique abbreviated ID:
162
+
163
+ ```console
164
+ git rev-parse --short=12 HEAD
165
+ ```
166
+
167
+ Record that returned value in the brief and reuse it exactly; the short ID avoids
168
+ manually reproducing a long opaque hash. Before handing off any change, including
169
+ document-only work, run:
170
+
171
+ ```console
172
+ opdev documents review --base START_COMMIT
173
+ ```
174
+
175
+ Replace START_COMMIT with that recorded commit. Add `--allow ROLE` for each document
176
+ owner justified by the accepted brief; omit it when no catalog document should change.
177
+ Do not substitute a moving HEAD after committing. This read-only operation is distinct
178
+ from `documents validate`, configured checks and a bare Git diff. Report its observed
179
+ status and review the actual diff against the brief. An accepted technical edit still
180
+ has a decision-review finding; explain the separate substantive review without calling
181
+ it an automatic pass. Detailed interpretation and owned-edit recovery are in the
182
+ [change procedure](references/development.md#change-brief-and-checkpoint).
183
+ If resolution fails, compare the argument character-for-character with the original
184
+ recorded output and correct any transcription before retrying. Repeating the same
185
+ mistyped value does not establish missing history. If the original commit truly
186
+ cannot be recovered, report scope verification unavailable; never substitute another
187
+ base or invent a clean result.
188
+
189
+ Use the Python CLI for configured operations; no alternate host policy engine,
190
+ automatic subagent hierarchy, hidden full CI or permanent evidence ledger.
@@ -0,0 +1,144 @@
1
+ # Setup, adoption and upgrades
2
+
3
+ Determine whether the request concerns runtime setup, adoption or an upgrade.
4
+ Installing the tool/plugin does not adopt a project. Reuse the user's existing
5
+ authorization; ask only for consequential unresolved choices, not routine wording.
6
+
7
+ ## Select tools
8
+
9
+ Use ordinary uv installation and the host's native plugin mechanism with an
10
+ explicitly selected release and environment. The plugin and Python distribution
11
+ ship together; compare the CLI's version identity with the package identity.
12
+ Do not infer the runtime from a bare `opdev` name or install with a command that
13
+ silently fetches an unselected latest version. Missing tools need an installation
14
+ offer. Preserve unrelated global tools, credentials and host settings.
15
+
16
+ ## Adopt
17
+
18
+ For an empty project, begin [design discovery](design.md), not tool scaffolding.
19
+ For existing code, inspect relevant code, tests, CI and instructions; distinguish
20
+ observed facts, inferred intent and proposed changes. Preserve adequate tooling and
21
+ approved decisions. Ask about consequential gaps, including stack, formatter,
22
+ linter, testing and delivery expectations. Never invent approval or silently mark
23
+ an unresolved practice unnecessary. Explain any deliberately deferred choice.
24
+
25
+ Assess existing code against the [coding practices](engineering.md#coding-practices)
26
+ and its accepted conventions. Retain sound tools and boundaries; identify concrete
27
+ gaps instead of treating existing practices as automatically compliant. Resolve
28
+ required changes within adoption or explicitly track incomplete work. Do not waive
29
+ real defects, but do not rewrite a sound architecture or reformat the repository
30
+ solely to match agent preferences. Keep mechanical migrations separately reviewable.
31
+ Apply [repository organization](engineering.md#repository-organization) to code,
32
+ resources, tests, tooling and generated/temporary material. Inspect real consumers
33
+ and native discovery before moving files; retain legitimate versioned generated
34
+ inputs and fix concrete ownership or lifecycle problems rather than imposing a tree.
35
+
36
+ Resolve the [complexity policy](design.md) for each relevant language and scope.
37
+ Retain suitable native tools, inspect existing findings and choose justified limits;
38
+ do not apply a blanket legacy exemption or weaken gates to make adoption pass.
39
+ Refactor useful boundaries, document narrow explained exceptions, or track unresolved
40
+ violations explicitly. Missing trustworthy analysis needs a documented limitation
41
+ and proportionate review, not a fabricated pass. Report configured gates separately
42
+ from analyzers actually executed, and keep exact rules in their native configuration.
43
+
44
+ Every adopted project needs the mandatory [document owners](design.md#document-owners)
45
+ and any justified selected optional technical roles. Infer supported content from
46
+ existing software, but resolve uncertainty with the developer. Keep each concern
47
+ with its owner; links supplement content rather than replace it. Preserve actual
48
+ structure and useful boundaries while applying the
49
+ [source-organization procedure](engineering.md#source-organization). Infer durable
50
+ intent and rationale from the code and native settings; do not copy their module
51
+ inventory into architecture.md. During an authorized document migration, separate
52
+ accepted constraints from observations of current code: preserve the constraints
53
+ and remove copied source inventories. An older approved document that deliberately
54
+ mandates particular ownership or interfaces needs decision reconciliation under the
55
+ upgrade's authority; do not silently discard that constraint or pretend its meaning
56
+ is already migrated. User
57
+ documentation is developer-owned: do not create, mandate or reorganize its docs
58
+ directory. Run `opdev documents validate` after saving the catalog; file presence
59
+ and structure do not establish substantive acceptance.
60
+
61
+ Prepare exact configuration using the project's tools. Inspect
62
+ `init --config FILE --plan` before create-only initialization. Review existing
63
+ AGENTS.md/CLAUDE.md routing explicitly; init preserves them. Use small additive
64
+ entry points without replacing unrelated instructions. Validate configuration,
65
+ then exercise appropriate checks once the design and setup are authorized.
66
+ Preserving an existing host file does not mean leaving missing routing unresolved:
67
+ under the authorized adoption, add the missing OpDev pointers and read both host
68
+ files back. If that edit is blocked, report adoption incomplete instead of done.
69
+ Initialization, file presence and passing commands are different from adoption
70
+ completion. Report unresolved choices and unverified boundaries honestly.
71
+
72
+ ### Require the protected merge path
73
+
74
+ The protected integration rule is mandatory, not a recommendation or an adoption
75
+ choice that can be waived. State plainly: **Direct pushes to the integration branch
76
+ are prohibited. Hosted adoption is incomplete until the provider enforces the
77
+ protected merge/pull-request path.** This also applies to single-developer projects
78
+ and does not require human reviewers.
79
+
80
+ Identify the actual integration branch from project decisions and provider state;
81
+ do not assume its name or rename it. Inspect effective permissions, inherited and
82
+ overlapping rules, required check producers, and maintainer/administrator/app/bot
83
+ bypasses. On GitLab, set Allowed to push and merge to No one while retaining the
84
+ intended Allowed to merge access; require successful pipelines and disallow merging
85
+ skipped pipelines. On GitHub, require pull requests and the intended checks, apply
86
+ rules to administrators, and remove integration bypass grants. Force pushes must
87
+ remain disabled. A required green job must mean its commands actually ran.
88
+
89
+ Use existing authorized setup/upgrade scope to configure protection and read it
90
+ back; resolve missing authority or access rather than silently changing unrelated
91
+ settings. Report settings inspection separately from hosted enforcement testing:
92
+ a CI YAML file, local pass or no-op push does not prove a prohibited update would
93
+ be rejected. Never test rejection by risking a real integration-branch update.
94
+
95
+ If enforcement is unavailable, leave hosted adoption/integration incomplete and
96
+ track the blocker. Do not mark it optional, ignored or satisfied by developer
97
+ acceptance. For an empty or local-only project, continue local design, initialization
98
+ and work-branch development; arrange an authorized protected destination before
99
+ remote integration. Do not use a first push, bootstrap, hotfix or release as a
100
+ bypass. Do not purchase provider features or alter the repository's visibility to
101
+ obtain protection without separate authority. An unsupported host remains a blocker.
102
+
103
+ On upgrades, remove obsolete generic text permitting direct pushes while preserving
104
+ unrelated project decisions. Recheck existing provider protections even when local
105
+ setup already exists. A conflict with the mandatory rule must stay explicit; it
106
+ cannot be preserved as a compliant legacy exception.
107
+
108
+ After accepted designs and configuration, lead [phased planning](planning.md)
109
+ without waiting for repeated "what next?" prompts. Track work remotely when the
110
+ provider is configured; a conversation proposal is sufficient before setup. Do not
111
+ create a temporary backlog in the repository to compensate for a missing tracker.
112
+
113
+ ## Upgrade deliberately
114
+
115
+ Inspect the current runtime, package and project instructions. Propose the exact
116
+ relevant changes, preserve decisions, and use existing scoped upgrade authority.
117
+ For an older copied generic guide, separate project-specific constraints from
118
+ reusable procedures. Move only the generic procedures to the installed skill;
119
+ retain all actual project constraints in `.opdev/guidance.md` or their catalog owner.
120
+ Keep the replacement guide to those constraints and routing. Do not paraphrase the
121
+ skill's generic approval, check or publication rules into a second local procedure;
122
+ that can accidentally authorize publication at integration. Release still requires
123
+ its own explicit authority.
124
+ Show and review the diff; never replace a customized guide blindly or call init
125
+ over an initialized project. Do not retain a competing legacy workflow as an archive.
126
+ For a document-layout migration, map every old decision to its fixed owner, select
127
+ only justified optional roles, preserve detailed contracts, repair local links and
128
+ compare the saved meaning. Resolve all unknown files deliberately; never move
129
+ unclassified content into an archive or generate an extra document category.
130
+ Keep temporary conservation notes outside the repository and remove superseded
131
+ owned copies only after their decisions are verified at the destinations.
132
+ Review both conservation and placement: compare each old decision with its saved
133
+ destination file and section. A whole-document sentence count or set comparison
134
+ can preserve every word while putting a dependency rule under state ownership.
135
+ Use the catalog's responsibilities; where a decision genuinely spans roles, choose
136
+ one appropriate authoritative owner and link it where needed. Do not duplicate it
137
+ or mistake a preferred location for the only valid one. Review the new files too:
138
+ an ordinary Git diff omits untracked destinations. Apply the
139
+ [architecture content review](engineering.md#architecture-content-review) to the
140
+ saved result: conserving decisions does not justify conserving a prose implementation map.
141
+ Use the [document-only feedback boundary](design.md#document-owners):
142
+ `opdev documents validate` checks the resulting structure, not approval or meaning.
143
+ Git history supplies recovery. Verify routing in fresh context and confirm the
144
+ runtime/package pair before completion. No automatic migration framework or updater.