@1aboveio/engineering-skills 0.0.0-stage → 0.1.1

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 (233) hide show
  1. package/README.md +28 -2
  2. package/package.json +34 -4
  3. package/skills/better-review/LICENSE +3 -0
  4. package/skills/better-review/SKILL.md +249 -0
  5. package/skills/better-review/agents/openai.yaml +9 -0
  6. package/skills/better-review/references/domain-hazards.md +53 -0
  7. package/skills/better-review/references/passes.md +147 -0
  8. package/skills/better-review/references/result.md +151 -0
  9. package/skills/better-review/release-check.mjs +93 -0
  10. package/skills/better-review/scripts/pr-context.mjs +212 -0
  11. package/skills/better-review/scripts/pr-context.test.mjs +168 -0
  12. package/skills/better-review/scripts/rereview-scope.mjs +503 -0
  13. package/skills/better-review/scripts/rereview-scope.test.mjs +587 -0
  14. package/skills/better-review/scripts/scan-diff.mjs +365 -0
  15. package/skills/better-review/scripts/scan-diff.test.mjs +414 -0
  16. package/skills/better-review/scripts/vendor-sync.test.mjs +96 -0
  17. package/skills/e2e-test/LICENSE +3 -0
  18. package/skills/e2e-test/SKILL.md +98 -0
  19. package/skills/e2e-test/assets/ci-gates.cloudbuild.yaml +24 -0
  20. package/skills/e2e-test/references/authoring/auth-flows.md +159 -0
  21. package/skills/e2e-test/references/authoring/playwright-config.md +73 -0
  22. package/skills/e2e-test/references/authoring/playwright-patterns.md +144 -0
  23. package/skills/e2e-test/references/ci-integration.md +25 -0
  24. package/skills/e2e-test/references/ci-playwright-container.md +290 -0
  25. package/skills/e2e-test/references/presentation-sweep.md +104 -0
  26. package/skills/e2e-test/references/reviewing.md +41 -0
  27. package/skills/e2e-test/references/route-manifest.md +51 -0
  28. package/skills/e2e-test/release-check.mjs +93 -0
  29. package/skills/e2e-test/scripts/detect-routes-nextjs.mjs +200 -0
  30. package/skills/e2e-test/scripts/presentation-checks.mjs +171 -0
  31. package/skills/e2e-test/scripts/presentation-checks.test.mjs +106 -0
  32. package/skills/e2e-test/scripts/presentation-perceivability.mjs +179 -0
  33. package/skills/e2e-test/scripts/presentation-perceivability.test.mjs +117 -0
  34. package/skills/e2e-test/scripts/presentation-reachability.mjs +154 -0
  35. package/skills/e2e-test/scripts/presentation-reachability.test.mjs +69 -0
  36. package/skills/e2e-test/scripts/presentation-render-health.mjs +141 -0
  37. package/skills/e2e-test/scripts/presentation-render-health.test.mjs +98 -0
  38. package/skills/e2e-test/scripts/presentation-sweep.mjs +147 -0
  39. package/skills/e2e-test/scripts/presentation-sweep.test.mjs +71 -0
  40. package/skills/e2e-test/scripts/presentation-temporal.mjs +127 -0
  41. package/skills/e2e-test/scripts/presentation-temporal.test.mjs +59 -0
  42. package/skills/e2e-test/scripts/project-route-manifest.mjs +82 -0
  43. package/skills/e2e-test/scripts/project-route-manifest.test.mjs +76 -0
  44. package/skills/e2e-test/scripts/validate-manifest.mjs +106 -0
  45. package/skills/engineering-runtime/LICENSE +3 -0
  46. package/skills/engineering-runtime/SKILL.md +11 -0
  47. package/skills/engineering-runtime/agents/openai.yaml +6 -0
  48. package/skills/engineering-runtime/coherence/workflow.json +597 -0
  49. package/skills/engineering-runtime/engineering-runtime.test.mjs +68 -0
  50. package/skills/engineering-runtime/release-check.mjs +93 -0
  51. package/skills/engineering-runtime/scripts/exact-head-artifact.mjs +131 -0
  52. package/skills/engineering-runtime/scripts/head-check-set.mjs +398 -0
  53. package/skills/engineering-runtime/scripts/invocation-policy.mjs +187 -0
  54. package/skills/engineering-runtime/scripts/invocation-policy.test.mjs +95 -0
  55. package/skills/engineering-runtime/scripts/main-module.mjs +79 -0
  56. package/skills/engineering-runtime/scripts/main-module.test.mjs +288 -0
  57. package/skills/engineering-runtime/scripts/mergify-yaml.mjs +11 -0
  58. package/skills/engineering-runtime/scripts/package-lock.json +43 -0
  59. package/skills/engineering-runtime/scripts/package.json +10 -0
  60. package/skills/engineering-runtime/scripts/required-check-plan.mjs +223 -0
  61. package/skills/engineering-runtime/scripts/required-check-plan.test.mjs +96 -0
  62. package/skills/engineering-runtime/scripts/review-completion.mjs +56 -0
  63. package/skills/engineering-runtime/scripts/workflow-coherence.mjs +595 -0
  64. package/skills/engineering-runtime/scripts/workflow-policy.mjs +189 -0
  65. package/skills/engineering-runtime/scripts/yaml-mapping.mjs +18 -0
  66. package/skills/ensure-coverage/LICENSE +3 -0
  67. package/skills/ensure-coverage/SKILL.md +129 -0
  68. package/skills/ensure-coverage/references/breadth/coverage-ledger.md +92 -0
  69. package/skills/ensure-coverage/references/breadth/inventory-contract.md +85 -0
  70. package/skills/ensure-coverage/references/breadth/surface-baseline.md +44 -0
  71. package/skills/ensure-coverage/references/breadth/surface-discovery.md +16 -0
  72. package/skills/ensure-coverage/references/depth/characterization.md +68 -0
  73. package/skills/ensure-coverage/references/depth/coverage.config.example.json +19 -0
  74. package/skills/ensure-coverage/references/depth/grading.md +35 -0
  75. package/skills/ensure-coverage/references/depth/mock-policy.md +57 -0
  76. package/skills/ensure-coverage/references/depth/test-smells.md +39 -0
  77. package/skills/ensure-coverage/references/enforcement/ci-contract.md +44 -0
  78. package/skills/ensure-coverage/references/examples/coverage-ledger.md +110 -0
  79. package/skills/ensure-coverage/references/examples/refund-flow.md +35 -0
  80. package/skills/ensure-coverage/references/presentation/axis.md +64 -0
  81. package/skills/ensure-coverage/references/process/audit-mode.md +27 -0
  82. package/skills/ensure-coverage/references/process/output-template.md +139 -0
  83. package/skills/ensure-coverage/references/process/test-strategy.md +56 -0
  84. package/skills/ensure-coverage/release-check.mjs +93 -0
  85. package/skills/ensure-coverage/schemas/coverage-config.schema.json +67 -0
  86. package/skills/ensure-coverage/schemas/coverage-file.schema.json +140 -0
  87. package/skills/ensure-coverage/scripts/README.md +99 -0
  88. package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.mjs +182 -0
  89. package/skills/ensure-coverage/scripts/adapters/nextjs-inventory.test.mjs +96 -0
  90. package/skills/ensure-coverage/scripts/check-quarantine-expiry.mjs +105 -0
  91. package/skills/ensure-coverage/scripts/check-quarantine-expiry.test.mjs +47 -0
  92. package/skills/ensure-coverage/scripts/ci-audit.mjs +137 -0
  93. package/skills/ensure-coverage/scripts/ci-audit.test.mjs +86 -0
  94. package/skills/ensure-coverage/scripts/coverage-ledger.mjs +674 -0
  95. package/skills/ensure-coverage/scripts/coverage-ledger.test.mjs +447 -0
  96. package/skills/ensure-coverage/scripts/design-parity.mjs +591 -0
  97. package/skills/ensure-coverage/scripts/design-parity.test.mjs +552 -0
  98. package/skills/ensure-coverage/scripts/lint-tests.mjs +282 -0
  99. package/skills/ensure-coverage/scripts/lint-tests.test.mjs +289 -0
  100. package/skills/ensure-coverage/scripts/mock-policy-config.mjs +176 -0
  101. package/skills/ensure-coverage/scripts/mock-policy-config.test.mjs +119 -0
  102. package/skills/ensure-coverage/scripts/package.json +19 -0
  103. package/skills/golden-path/LICENSE +3 -0
  104. package/skills/golden-path/SKILL.md +230 -0
  105. package/skills/golden-path/agents/openai.yaml +3 -0
  106. package/skills/golden-path/assets/golden-paths.example.json +57 -0
  107. package/skills/golden-path/references/contract.md +239 -0
  108. package/skills/golden-path/references/migration.md +111 -0
  109. package/skills/golden-path/release-check.mjs +93 -0
  110. package/skills/golden-path/scripts/golden-path-core.mjs +1779 -0
  111. package/skills/golden-path/scripts/golden-path.mjs +6 -0
  112. package/skills/golden-path/scripts/golden-path.test.mjs +1457 -0
  113. package/skills/harness-runtime/LICENSE +3 -0
  114. package/skills/harness-runtime/SKILL.md +19 -0
  115. package/skills/harness-runtime/agents/openai.yaml +6 -0
  116. package/skills/harness-runtime/bin/discover-models.mjs +4 -0
  117. package/skills/harness-runtime/bin/model-catalog.mjs +4 -0
  118. package/skills/harness-runtime/contracts.md +15 -0
  119. package/skills/harness-runtime/discover-models.mjs +392 -0
  120. package/skills/harness-runtime/discover-models.test.mjs +363 -0
  121. package/skills/harness-runtime/fixtures/native-question-schemas.json +33 -0
  122. package/skills/harness-runtime/fixtures/question-responses.json +54 -0
  123. package/skills/harness-runtime/harness-runtime.test.mjs +967 -0
  124. package/skills/harness-runtime/index.mjs +767 -0
  125. package/skills/harness-runtime/model-catalog-seed.test.mjs +829 -0
  126. package/skills/harness-runtime/model-catalog.mjs +787 -0
  127. package/skills/harness-runtime/model-catalog.test.mjs +366 -0
  128. package/skills/harness-runtime/native-question-contracts.md +37 -0
  129. package/skills/harness-runtime/references/model-catalog-seed.json +408 -0
  130. package/skills/harness-runtime/references/model-catalog.md +57 -0
  131. package/skills/harness-runtime/release-check.mjs +93 -0
  132. package/skills/resolve-issues/LICENSE +3 -0
  133. package/skills/resolve-issues/SKILL.md +250 -0
  134. package/skills/resolve-issues/agents/openai.yaml +9 -0
  135. package/skills/resolve-issues/plugin-hooks.json +17 -0
  136. package/skills/resolve-issues/references/canary.md +28 -0
  137. package/skills/resolve-issues/references/ci.md +105 -0
  138. package/skills/resolve-issues/references/done.md +25 -0
  139. package/skills/resolve-issues/references/dropbox.md +90 -0
  140. package/skills/resolve-issues/references/expire.md +318 -0
  141. package/skills/resolve-issues/references/exploration.md +202 -0
  142. package/skills/resolve-issues/references/implementation.md +303 -0
  143. package/skills/resolve-issues/references/preflight.md +445 -0
  144. package/skills/resolve-issues/references/review.md +228 -0
  145. package/skills/resolve-issues/references/shared-modules.md +44 -0
  146. package/skills/resolve-issues/references/task-plan.md +264 -0
  147. package/skills/resolve-issues/release-check.mjs +93 -0
  148. package/skills/resolve-issues/scripts/cleanup-runs.mjs +364 -0
  149. package/skills/resolve-issues/scripts/cleanup-runs.test.mjs +280 -0
  150. package/skills/resolve-issues/scripts/discover-models.mjs +9 -0
  151. package/skills/resolve-issues/scripts/dropbox.mjs +473 -0
  152. package/skills/resolve-issues/scripts/dropbox.test.mjs +346 -0
  153. package/skills/resolve-issues/scripts/findings-reuse.mjs +98 -0
  154. package/skills/resolve-issues/scripts/findings-reuse.test.mjs +88 -0
  155. package/skills/resolve-issues/scripts/github-reviews.mjs +384 -0
  156. package/skills/resolve-issues/scripts/github-reviews.test.mjs +264 -0
  157. package/skills/resolve-issues/scripts/install-hooks.mjs +135 -0
  158. package/skills/resolve-issues/scripts/install-hooks.test.mjs +79 -0
  159. package/skills/resolve-issues/scripts/issue-tree.mjs +162 -0
  160. package/skills/resolve-issues/scripts/issue-tree.test.mjs +107 -0
  161. package/skills/resolve-issues/scripts/manual-invocation.test.mjs +14 -0
  162. package/skills/resolve-issues/scripts/model-catalog.mjs +9 -0
  163. package/skills/resolve-issues/scripts/next-actions-capacity.test.mjs +149 -0
  164. package/skills/resolve-issues/scripts/next-actions.mjs +856 -0
  165. package/skills/resolve-issues/scripts/next-actions.test.mjs +915 -0
  166. package/skills/resolve-issues/scripts/plan-sync.mjs +269 -0
  167. package/skills/resolve-issues/scripts/plan-sync.test.mjs +156 -0
  168. package/skills/resolve-issues/scripts/preflight-models.mjs +736 -0
  169. package/skills/resolve-issues/scripts/preflight-models.test.mjs +448 -0
  170. package/skills/resolve-issues/scripts/ready-check.mjs +185 -0
  171. package/skills/resolve-issues/scripts/ready-check.test.mjs +217 -0
  172. package/skills/resolve-issues/scripts/rehydrate.mjs +98 -0
  173. package/skills/resolve-issues/scripts/rehydrate.test.mjs +91 -0
  174. package/skills/resolve-issues/scripts/review-verdict.mjs +509 -0
  175. package/skills/resolve-issues/scripts/review-verdict.test.mjs +1060 -0
  176. package/skills/resolve-issues/scripts/size-check.mjs +492 -0
  177. package/skills/resolve-issues/scripts/size-check.test.mjs +458 -0
  178. package/skills/resolve-release/LICENSE +3 -0
  179. package/skills/resolve-release/SKILL.md +215 -0
  180. package/skills/resolve-release/agents/openai.yaml +8 -0
  181. package/skills/resolve-release/flows/cloud-run-canary.md +13 -0
  182. package/skills/resolve-release/flows/cloud-run.md +7 -0
  183. package/skills/resolve-release/flows/root-tag-npm.md +13 -0
  184. package/skills/resolve-release/flows/workspace-npm.md +22 -0
  185. package/skills/resolve-release/references/canary.md +51 -0
  186. package/skills/resolve-release/references/candidate.md +41 -0
  187. package/skills/resolve-release/references/cut.md +131 -0
  188. package/skills/resolve-release/references/dark-launch.md +66 -0
  189. package/skills/resolve-release/references/flows.md +150 -0
  190. package/skills/resolve-release/references/preflight.md +154 -0
  191. package/skills/resolve-release/references/prepared-metadata.md +260 -0
  192. package/skills/resolve-release/references/promotion.md +82 -0
  193. package/skills/resolve-release/references/publish.md +232 -0
  194. package/skills/resolve-release/references/workspace-npm.md +103 -0
  195. package/skills/resolve-release/release-check.mjs +93 -0
  196. package/skills/resolve-release/scripts/apply.mjs +212 -0
  197. package/skills/resolve-release/scripts/apply.test.mjs +99 -0
  198. package/skills/resolve-release/scripts/dark-flags.mjs +134 -0
  199. package/skills/resolve-release/scripts/dark-flags.test.mjs +100 -0
  200. package/skills/resolve-release/scripts/flow.mjs +500 -0
  201. package/skills/resolve-release/scripts/flow.test.mjs +340 -0
  202. package/skills/resolve-release/scripts/green-head.mjs +231 -0
  203. package/skills/resolve-release/scripts/green-head.test.mjs +101 -0
  204. package/skills/resolve-release/scripts/npm-version-absence.mjs +138 -0
  205. package/skills/resolve-release/scripts/npm-version-absence.test.mjs +426 -0
  206. package/skills/resolve-release/scripts/plan-npm.test.mjs +659 -0
  207. package/skills/resolve-release/scripts/plan-toml-boundary.test.mjs +317 -0
  208. package/skills/resolve-release/scripts/plan-uv.test.mjs +291 -0
  209. package/skills/resolve-release/scripts/plan.mjs +806 -0
  210. package/skills/resolve-release/scripts/plan.test.mjs +428 -0
  211. package/skills/rush-issues/LICENSE +3 -0
  212. package/skills/rush-issues/SKILL.md +58 -0
  213. package/skills/rush-issues/agents/openai.yaml +8 -0
  214. package/skills/rush-issues/rehydrate.mjs +10 -0
  215. package/skills/rush-issues/release-check.mjs +93 -0
  216. package/skills/rush-release/LICENSE +3 -0
  217. package/skills/rush-release/SKILL.md +35 -0
  218. package/skills/rush-release/agents/openai.yaml +8 -0
  219. package/skills/rush-release/release-check.mjs +93 -0
  220. package/skills/test-quality/LICENSE +3 -0
  221. package/skills/test-quality/SKILL.md +79 -0
  222. package/skills/test-quality/references/audit.md +80 -0
  223. package/skills/test-quality/references/lint.md +24 -0
  224. package/skills/test-quality/references/principles.md +143 -0
  225. package/skills/test-quality/references/testing-conventions.md +9 -0
  226. package/skills/test-quality/release-check.mjs +93 -0
  227. package/skills/test-quality/scripts/lint-tests.mjs +574 -0
  228. package/skills/test-quality/scripts/lint-tests.test.mjs +591 -0
  229. package/skills/test-quality/scripts/mock-policy-config.mjs +176 -0
  230. package/skills/test-quality/scripts/mock-policy-config.test.mjs +119 -0
  231. package/skills/test-quality/scripts/persist-conventions-core.mjs +117 -0
  232. package/skills/test-quality/scripts/persist-conventions.mjs +17 -0
  233. package/skills/test-quality/scripts/persist-conventions.test.mjs +104 -0
@@ -0,0 +1,68 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
4
+ import { dirname, join, relative, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const RUNTIME_DIR = dirname(fileURLToPath(import.meta.url));
8
+ const REPO_ROOT = join(RUNTIME_DIR, '..', '..', '..');
9
+ const MANIFEST = JSON.parse(readFileSync(join(REPO_ROOT, 'skills', 'distribution', 'manifest.json'), 'utf8'));
10
+
11
+ // @covers package:engineering-runtime
12
+ // @level integration
13
+ test('runtime parser dependency metadata lives in the installed scripts directory', () => {
14
+ const scripts = join(RUNTIME_DIR, 'scripts');
15
+ const packageJson = JSON.parse(readFileSync(join(scripts, 'package.json'), 'utf8'));
16
+ const packageLock = JSON.parse(readFileSync(join(scripts, 'package-lock.json'), 'utf8'));
17
+
18
+ assert.equal(existsSync(join(RUNTIME_DIR, 'package.json')), false);
19
+ assert.equal(existsSync(join(RUNTIME_DIR, 'package-lock.json')), false);
20
+ // The lockfile must install exactly the version package.json declares.
21
+ assert.ok(packageJson.dependencies['js-yaml'], 'the runtime parser depends on js-yaml');
22
+ assert.equal(packageLock.packages['node_modules/js-yaml'].version, packageJson.dependencies['js-yaml']);
23
+ });
24
+
25
+ function modules(dir) {
26
+ const found = [];
27
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
28
+ if (entry.name === 'node_modules' || entry.name.endsWith('-workspace')) continue;
29
+ const path = join(dir, entry.name);
30
+ if (entry.isDirectory()) found.push(...modules(path));
31
+ else if (entry.name.endsWith('.mjs') && !entry.name.endsWith('.test.mjs')) found.push(path);
32
+ }
33
+ return found;
34
+ }
35
+
36
+ // @covers package:engineering-runtime
37
+ // @level integration
38
+ test('every first-party Workflow consumer resolves one implementation in source and flat layouts', () => {
39
+ const workflow = MANIFEST.groups.find((group) => group.id === 'engineering-workflow');
40
+ const canonical = join(RUNTIME_DIR, 'scripts', 'main-module.mjs');
41
+ const flatCanonical = join('/flat-skills', 'engineering-runtime', 'scripts', 'main-module.mjs');
42
+ const consumers = [];
43
+
44
+ for (const member of workflow.members.filter((candidate) => candidate.role === 'skill')) {
45
+ const skillDir = join(REPO_ROOT, member.path);
46
+ for (const file of modules(skillDir)) {
47
+ const text = readFileSync(file, 'utf8');
48
+ if (!/\bisMainModule\s*\(/.test(text)) continue;
49
+ const staticImport = /import\s+\{\s*isMainModule\s*\}\s+from\s+['"]([^'"]+)['"]/.exec(text);
50
+ const dynamicImport = /await import\(['"]([^'"]+)['"]\)/.exec(text);
51
+ const imported = staticImport ?? dynamicImport;
52
+ assert.ok(imported, `${relative(REPO_ROOT, file)} calls isMainModule without resolving it from the runtime package`);
53
+ assert.equal(resolve(dirname(file), imported[1]), canonical, `${relative(REPO_ROOT, file)} misses the source runtime`);
54
+
55
+ const installedFile = join('/flat-skills', member.installName, relative(skillDir, file));
56
+ assert.equal(
57
+ resolve(dirname(installedFile), imported[1]),
58
+ flatCanonical,
59
+ `${relative(REPO_ROOT, file)} misses the flat-installed runtime`,
60
+ );
61
+ consumers.push(relative(REPO_ROOT, file));
62
+ }
63
+ }
64
+
65
+ // Shipped members only: the archived resolve-issues/resolve-release scripts left this census when
66
+ // those names became aliases (they were never packaged).
67
+ assert.ok(consumers.length >= 17, `the Workflow consumer census found only ${consumers.length} guarded scripts`);
68
+ });
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from 'node:child_process';
3
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
+ import { homedir } from 'node:os';
5
+ import { dirname, join } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ const DAY_MS = 24 * 60 * 60 * 1000;
9
+ const WEEK_MS = 7 * DAY_MS;
10
+ const here = dirname(fileURLToPath(import.meta.url));
11
+
12
+ function readJson(path, fallback = {}) {
13
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
14
+ }
15
+
16
+ function frontmatterValue(text, key) {
17
+ const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
18
+ const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
19
+ return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
20
+ }
21
+
22
+ function repositoryOf(source) {
23
+ const value = String(source ?? '').trim();
24
+ const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
25
+ return match?.[1] ?? null;
26
+ }
27
+
28
+ function stableVersion(value) {
29
+ const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
30
+ return match ? match.slice(1).map(Number) : null;
31
+ }
32
+
33
+ function newer(left, right) {
34
+ for (let index = 0; index < 3; index += 1) {
35
+ if (left[index] !== right[index]) return left[index] > right[index];
36
+ }
37
+ return false;
38
+ }
39
+
40
+ function writeCache(path, value) {
41
+ try {
42
+ mkdirSync(dirname(path), { recursive: true });
43
+ writeFileSync(path, JSON.stringify(value));
44
+ } catch { /* A read-only cache must not block skill use. */ }
45
+ }
46
+
47
+ function main(now = Date.now()) {
48
+ if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
49
+ const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
@@ -0,0 +1,131 @@
1
+ // Shared read-only validator for exact-head CI artifacts. The mutating adapter lives
2
+ // in resolve-issues; consumers import this contract so review and integration use the
3
+ // same fail-closed definition of valid evidence.
4
+ import { locallyReproducedJobs, validatePublishOnlyEvidence, validateRequiredCheckExecution, validateRequiredCheckPlan } from './required-check-plan.mjs'
5
+
6
+ export const EXACT_HEAD_ARTIFACT_VERSION = 2
7
+ export const EXACT_HEAD_COLLECTION_MODES = Object.freeze(['choreographed', 'observed-existing-run'])
8
+
9
+ function isObject(value) {
10
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
11
+ }
12
+
13
+ function stable(value) {
14
+ if (Array.isArray(value)) return value.map(stable)
15
+ if (!isObject(value)) return value
16
+ return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]))
17
+ }
18
+
19
+ export function sameExactHeadState(left, right) {
20
+ return JSON.stringify(stable(left)) === JSON.stringify(stable(right))
21
+ }
22
+
23
+ export function providerWorkflowIdentityMatches(expected, identity) {
24
+ if (typeof expected !== 'string' || !expected.trim() || !isObject(identity)) return false
25
+ const aliases = [identity.id, identity.name, identity.path]
26
+ .filter((value) => (typeof value === 'string' && value.trim()) || typeof value === 'number')
27
+ .map(String)
28
+ if (typeof identity.path === 'string') aliases.push(identity.path.split('/').at(-1))
29
+ return aliases.includes(expected)
30
+ }
31
+
32
+ function validateProviderWorkflowIdentity(identity) {
33
+ const errors = []
34
+ if (!isObject(identity)) return ['artifact.workflow.provider must preserve provider-issued workflow identity']
35
+ if ((typeof identity.id !== 'string' && typeof identity.id !== 'number') || !String(identity.id).trim()) errors.push('artifact.workflow.provider.id must identify the provider workflow')
36
+ if (typeof identity.name !== 'string' || !identity.name.trim()) errors.push('artifact.workflow.provider.name must preserve the provider workflow name')
37
+ if (identity.path !== undefined && (typeof identity.path !== 'string' || !identity.path.trim())) errors.push('artifact.workflow.provider.path must be a non-empty string when present')
38
+ return errors
39
+ }
40
+
41
+ function classifyRawJobs(jobs, policy) {
42
+ const errors = []
43
+ if (!Array.isArray(jobs)) return { outcome: 'failure', errors: ['artifact.jobs must be an array'] }
44
+ if (!isObject(policy) || !Array.isArray(policy.requiredJobs) || !Array.isArray(policy.allowedSkippedJobs)) {
45
+ return { outcome: 'failure', errors: ['artifact.policy must preserve requiredJobs and allowedSkippedJobs arrays'] }
46
+ }
47
+ const byName = new Map()
48
+ for (const [index, job] of jobs.entries()) {
49
+ if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) {
50
+ errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
51
+ continue
52
+ }
53
+ if (byName.has(job.name)) errors.push(`artifact.jobs has duplicate/ambiguous evidence for ${job.name}`)
54
+ else byName.set(job.name, job)
55
+ }
56
+ const missing = policy.requiredJobs.filter((name) => !byName.has(name))
57
+ const notSuccessful = policy.requiredJobs.filter((name) => byName.has(name) && byName.get(name).conclusion !== 'success')
58
+ const allowedSkipped = new Set(policy.allowedSkippedJobs)
59
+ const disallowedSkipped = jobs.filter((job) => job?.conclusion === 'skipped' && !allowedSkipped.has(job.name)).map((job) => job.name)
60
+ const failed = jobs.filter((job) => job && !['success', 'skipped'].includes(job.conclusion)).map((job) => `${job.name} (${job.conclusion ?? 'pending'})`)
61
+ if (missing.length) errors.push(`required jobs missing: ${missing.join(', ')}`)
62
+ if (notSuccessful.length) errors.push(`required jobs not successful: ${notSuccessful.join(', ')}`)
63
+ if (disallowedSkipped.length) errors.push(`jobs skipped without policy allowance: ${disallowedSkipped.join(', ')}`)
64
+ if (failed.length) errors.push(`raw jobs contain failure states: ${failed.join(', ')}`)
65
+ let outcome = 'success'
66
+ if (jobs.length === 0) outcome = 'zero-job-workflow-failure'
67
+ else if (jobs.some((job) => job?.conclusion === 'cancelled')) outcome = 'cancelled'
68
+ else if (errors.length) outcome = 'failure'
69
+ else if (jobs.some((job) => job?.conclusion === 'skipped')) outcome = 'success-with-skipped'
70
+ return { outcome, errors }
71
+ }
72
+
73
+ export function validateExactHeadArtifact(artifact, { expectedHeadSha } = {}) {
74
+ const errors = []
75
+ if (!isObject(artifact)) return { ok: false, errors: ['exact-head artifact must be an object'] }
76
+ if (artifact.version !== EXACT_HEAD_ARTIFACT_VERSION) errors.push(`unsupported exact-head artifact version ${artifact.version}`)
77
+ if (artifact.kind !== 'exact-head-ci') errors.push('exact-head artifact kind must be "exact-head-ci"')
78
+ if (!EXACT_HEAD_COLLECTION_MODES.includes(artifact.collectionMode)) errors.push(`artifact.collectionMode must be one of ${EXACT_HEAD_COLLECTION_MODES.join('|')}`)
79
+ if (typeof artifact.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(artifact.repository)) errors.push('artifact.repository must be owner/name')
80
+ if (!Number.isInteger(artifact.pr) || artifact.pr < 1) errors.push('artifact.pr must be a positive integer')
81
+ if (typeof artifact.headSha !== 'string' || !/^[0-9a-f]{40}$/i.test(artifact.headSha)) errors.push('artifact.headSha must be a full 40-character commit SHA')
82
+ if (expectedHeadSha && artifact.headSha !== expectedHeadSha) errors.push(`exact-head artifact is STALE: stamped ${artifact.headSha}, expected ${expectedHeadSha}`)
83
+ const plan = validateRequiredCheckPlan(artifact.requiredCheckPlan, { expectedHeadSha: artifact.headSha })
84
+ errors.push(...plan.errors)
85
+ if (artifact.requiredCheckPlan?.repository !== artifact.repository) errors.push('requiredCheckPlan repository does not match artifact.repository')
86
+ const execution = validateRequiredCheckExecution(artifact.requiredCheckPlan, artifact.jobs, { expectedHeadSha: artifact.headSha })
87
+ errors.push(...execution.errors.filter((error) => !plan.errors.includes(error)))
88
+ const publishOnly = validatePublishOnlyEvidence(artifact.requiredCheckPlan, artifact.publishOnlyEvidence, { expectedHeadSha: artifact.headSha, expectedRepository: artifact.repository, expectedPr: artifact.pr })
89
+ errors.push(...publishOnly.errors)
90
+ if (!isObject(artifact.workflow) || typeof artifact.workflow.id !== 'string' || !artifact.workflow.id.trim()) errors.push('artifact.workflow.id must identify the requested provider workflow')
91
+ errors.push(...validateProviderWorkflowIdentity(artifact.workflow?.provider))
92
+ if (isObject(artifact.workflow?.provider) && !providerWorkflowIdentityMatches(artifact.workflow?.id, artifact.workflow.provider)) errors.push('provider workflow identity does not match artifact.workflow.id')
93
+ if (typeof artifact.workflow?.runId !== 'string' && typeof artifact.workflow?.runId !== 'number') errors.push('artifact.workflow.runId must identify the provider run')
94
+ if (artifact.workflow?.headSha !== artifact.headSha) errors.push('workflow headSha does not match artifact headSha')
95
+ if (!Array.isArray(artifact.jobs)) errors.push('artifact.jobs must be an array')
96
+ else for (const [index, job] of artifact.jobs.entries()) {
97
+ if (!isObject(job) || typeof job.name !== 'string' || !Object.hasOwn(job, 'conclusion')) errors.push(`artifact.jobs[${index}] must preserve name and conclusion`)
98
+ }
99
+ const expectedPolicy = {
100
+ requiredJobs: locallyReproducedJobs(artifact.requiredCheckPlan),
101
+ allowedSkippedJobs: artifact.requiredCheckPlan?.allowedSkippedJobs,
102
+ }
103
+ if (!sameExactHeadState(artifact.policy, expectedPolicy)) errors.push('artifact.policy must be derived exactly from requiredCheckPlan')
104
+ const raw = classifyRawJobs(artifact.jobs, artifact.policy)
105
+ errors.push(...raw.errors)
106
+ if (artifact.summary?.outcome !== raw.outcome) errors.push(`summary outcome "${artifact.summary?.outcome ?? 'missing'}" contradicts raw jobs outcome "${raw.outcome}"`)
107
+
108
+ if (artifact.collectionMode === 'choreographed') {
109
+ if (!Array.isArray(artifact.choreography) || artifact.choreography.length === 0) errors.push('choreographed artifacts must preserve the mutation choreography')
110
+ if (Object.hasOwn(artifact, 'observation')) errors.push('choreographed artifacts cannot claim observed-existing-run provenance')
111
+ if (artifact.restoration?.proved !== true) errors.push('live restoration was not proved')
112
+ if (!sameExactHeadState(artifact.snapshot, artifact.restoration?.observed)) errors.push('restoration observation does not equal the original snapshot')
113
+ }
114
+ if (artifact.collectionMode === 'observed-existing-run') {
115
+ if (Object.hasOwn(artifact, 'choreography')) errors.push('observed-existing-run artifacts cannot claim mutation choreography')
116
+ if (Object.hasOwn(artifact, 'restoration')) errors.push('observed-existing-run artifacts cannot contain a restoration claim')
117
+ if (Object.hasOwn(artifact, 'snapshot')) errors.push('observed-existing-run artifacts must use before/after observation provenance, not a choreography snapshot')
118
+ if (!isObject(artifact.observation) || !isObject(artifact.observation.before) || !isObject(artifact.observation.after)) {
119
+ errors.push('observed-existing-run artifacts require live PR observations before and after provider evidence acquisition')
120
+ } else {
121
+ if (artifact.observation.before.headSha !== artifact.headSha) errors.push('observed-existing-run before observation does not match artifact.headSha')
122
+ if (artifact.observation.after.headSha !== artifact.headSha) errors.push('observed-existing-run after observation does not match artifact.headSha')
123
+ }
124
+ }
125
+ if (!Array.isArray(artifact.errors)) errors.push('artifact.errors must be an array')
126
+ else if (artifact.errors.length) errors.push('passing exact-head artifacts cannot preserve collection errors')
127
+ if (artifact.status !== 'pass') errors.push(`exact-head status is "${artifact.status ?? 'missing'}", needs "pass"`)
128
+ if (!['success', 'success-with-skipped'].includes(artifact.summary?.outcome)) errors.push(`exact-head outcome is "${artifact.summary?.outcome ?? 'missing'}", not a passing outcome`)
129
+ if (!['success', 'success-with-skipped'].includes(raw.outcome)) errors.push(`raw jobs outcome "${raw.outcome}" is not passing`)
130
+ return { ok: errors.length === 0, errors }
131
+ }