@1aboveio/engineering-skills 0.1.10 → 0.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/package.json +2 -2
- package/skills/better-review/SKILL.md +37 -37
- package/skills/better-review/references/passes.md +35 -41
- package/skills/better-review/references/result.md +10 -9
- package/skills/e2e-test/SKILL.md +17 -17
- package/skills/e2e-test/references/authoring/playwright-config.md +11 -13
- package/skills/e2e-test/references/presentation-sweep.md +7 -7
- package/skills/e2e-test/references/reviewing.md +9 -11
- package/skills/e2e-test/references/route-manifest.md +1 -1
- package/skills/engineering/SKILL.md +124 -0
- package/skills/engineering/references/engineering-conventions.md +32 -0
- package/skills/engineering/references/feature-delivery.md +8 -0
- package/skills/engineering/references/init-scope.md +37 -0
- package/skills/engineering/scripts/init.mjs +160 -0
- package/skills/{contributing → engineering}/scripts/persist-conventions.mjs +1 -1
- package/skills/engineering-runtime/SKILL.md +1 -1
- package/skills/engineering-runtime/coherence/workflow.json +19 -19
- package/skills/engineering-runtime/scripts/workflow-policy.mjs +1 -1
- package/skills/ensure-coverage/SKILL.md +22 -109
- package/skills/ensure-coverage/references/breadth/coverage-ledger.md +7 -5
- package/skills/ensure-coverage/references/breadth/surface-baseline.md +4 -4
- package/skills/ensure-coverage/references/breadth/surface-discovery.md +3 -3
- package/skills/ensure-coverage/references/depth/characterization.md +4 -65
- package/skills/ensure-coverage/references/depth/grading.md +5 -7
- package/skills/ensure-coverage/references/depth/mock-policy.md +6 -12
- package/skills/ensure-coverage/references/enforcement/ci-contract.md +1 -1
- package/skills/ensure-coverage/references/presentation/axis.md +6 -6
- package/skills/ensure-coverage/references/process/audit-mode.md +7 -23
- package/skills/ensure-coverage/references/process/output-template.md +18 -133
- package/skills/ensure-coverage/references/process/test-strategy.md +7 -12
- package/skills/ensure-coverage/scripts/README.md +12 -4
- package/skills/golden-path/SKILL.md +1 -1
- package/skills/harness-runtime/SKILL.md +3 -1
- package/skills/harness-runtime/bin/workspaces.mjs +52 -0
- package/skills/harness-runtime/native-workspace.mjs +239 -0
- package/skills/harness-runtime/references/workspaces.md +78 -0
- package/skills/harness-runtime/workspace-lifecycle.mjs +2154 -0
- package/skills/resolve-issues/SKILL.md +40 -61
- package/skills/resolve-issues/references/ci.md +13 -3
- package/skills/resolve-issues/references/delivery-progress.md +4 -3
- package/skills/resolve-issues/references/done.md +11 -2
- package/skills/resolve-issues/references/expire.md +9 -2
- package/skills/resolve-issues/references/implementation.md +33 -17
- package/skills/resolve-issues/references/preflight.md +3 -1
- package/skills/resolve-issues/references/principles.md +52 -0
- package/skills/resolve-issues/references/review.md +25 -15
- package/skills/resolve-issues/references/task-plan.md +64 -27
- package/skills/resolve-issues/references/workspaces.md +164 -0
- package/skills/resolve-issues/scripts/cleanup-runs.mjs +185 -317
- package/skills/resolve-issues/scripts/next-actions.mjs +44 -7
- package/skills/resolve-issues/scripts/rehydrate.mjs +36 -2
- package/skills/resolve-issues/scripts/review-verdict.mjs +9 -8
- package/skills/resolve-issues/scripts/workspace-lifecycle.mjs +1 -0
- package/skills/resolve-release/SKILL.md +1 -1
- package/skills/rush-issues/SKILL.md +7 -5
- package/skills/rush-release/SKILL.md +1 -1
- package/skills/test-quality/SKILL.md +19 -4
- package/skills/test-quality/references/lint.md +1 -1
- package/skills/test-quality/references/principles.md +2 -2
- package/skills/test-quality/references/testing-conventions.md +1 -1
- package/skills/contributing/SKILL.md +0 -70
- /package/skills/{contributing → engineering}/LICENSE +0 -0
- /package/skills/{contributing → engineering}/references/tracker-conventions.md +0 -0
- /package/skills/{contributing → engineering}/release-check.mjs +0 -0
- /package/skills/{contributing → engineering}/scripts/persist-conventions-core.mjs +0 -0
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
//
|
|
12
12
|
// add-unit, drop-unit, set-deps, move-link, blocked-outside, cycle
|
|
13
13
|
// the plan differs from the spec's GitHub issue tree (plan-sync.mjs): apply
|
|
14
|
-
// it through
|
|
14
|
+
// it through the available checkpoint mechanism. --resume and --sync fetch the tree (one GraphQL
|
|
15
15
|
// query) and save it; every other call diffs the saved tree, with no
|
|
16
16
|
// GitHub call. Sync after the run files an issue
|
|
17
17
|
// unblock a unit marked blocked without a reason from BLOCK_REASONS
|
|
@@ -176,6 +176,12 @@ export function normalizeCapacity(input) {
|
|
|
176
176
|
const hasWorker = (u) => u.worker !== undefined && u.worker !== null && u.worker !== ''
|
|
177
177
|
const codeDone = (u) => u.stage === 'done'
|
|
178
178
|
|
|
179
|
+
export function workspaceCleanupSettled(unit) {
|
|
180
|
+
const result = unit.lifecycle?.cleanup
|
|
181
|
+
return typeof unit.headSha === 'string' && unit.headSha.length > 0 && result?.headSha === unit.headSha &&
|
|
182
|
+
(result.state === 'complete' || (result.state === 'retained' && typeof result.reason === 'string' && result.reason.trim().length > 0))
|
|
183
|
+
}
|
|
184
|
+
|
|
179
185
|
// Pure decision from the plan and each unit's newest review round.
|
|
180
186
|
// `capacity`: a fresh Harness snapshot, or an explicitly reconciled total workflow budget.
|
|
181
187
|
// Snapshot availableSlots is already net of all running and reserved workers.
|
|
@@ -191,6 +197,10 @@ const codeDone = (u) => u.stage === 'done'
|
|
|
191
197
|
// `key` is the result file, relative to the run, that a `decisions` entry's `answers` names.
|
|
192
198
|
export function nextActions(plan, reviews = {}, capacity, { resume = false, now, activity = {}, quietMinutes = DEFAULT_QUIET_MINUTES, sync = null, seen = {}, questions = {} } = {}) {
|
|
193
199
|
const effectiveCapacity = normalizeCapacity(capacity)
|
|
200
|
+
if (Array.isArray(plan?.units) && Array.isArray(plan?.issues) && JSON.stringify(plan.units) !== JSON.stringify(plan.issues)) {
|
|
201
|
+
throw new NextActionsError('task plan has conflicting units and issues rosters')
|
|
202
|
+
}
|
|
203
|
+
if (plan?.workspaceLifecycle !== undefined && plan.workspaceLifecycle !== 1) throw new NextActionsError('unsupported workspaceLifecycle version')
|
|
194
204
|
const saved = (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
|
|
195
205
|
if (!Array.isArray(saved) || saved.length === 0) throw new NextActionsError('task plan has no units')
|
|
196
206
|
const excluded = excludedIds(plan)
|
|
@@ -328,6 +338,17 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
328
338
|
}
|
|
329
339
|
const actions = []
|
|
330
340
|
const add = (action, u, detail) => actions.push({ action, unit: String(u.id), detail })
|
|
341
|
+
const managed = (u) => plan.workspaceLifecycle === 1 || u.lifecycle?.version === 1
|
|
342
|
+
for (const u of units) {
|
|
343
|
+
if (TERMINAL.has(u.status) && hasWorker(u) && (u.status !== 'blocked' || reasonOk(u))) {
|
|
344
|
+
add('check-worker', u, `unit ${u.id} is ${u.status} but still records worker ${u.worker}: collect its terminal result and stop its owned services before handoff or workspace cleanup; never remove a running environment`)
|
|
345
|
+
continue
|
|
346
|
+
}
|
|
347
|
+
if (!managed(u) || u.status !== 'succeeded' || !u.workspace) continue
|
|
348
|
+
if (!hasWorker(u) && !workspaceCleanupSettled(u)) {
|
|
349
|
+
add('cleanup-workspace', u, `unit ${u.id} landed: record lifecycle.cleanup with state applying and headSha ${u.headSha ?? '(record the delivered HEAD first)'}, then run cleanup-runs.mjs cleanup --run <run> --unit ${u.id} --revision <saved planRevision> --apply --json; inspect and persist the returned lifecycle. A refusal is retained with its reason, never complete; do this before finish and alongside independent units`)
|
|
350
|
+
}
|
|
351
|
+
}
|
|
331
352
|
const chainReady = []
|
|
332
353
|
const chainOpen = (u) => {
|
|
333
354
|
const id = String(u.id)
|
|
@@ -385,6 +406,7 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
385
406
|
const quietMs = quietMinutes * 60_000
|
|
386
407
|
for (const u of units) {
|
|
387
408
|
if (!hasWorker(u)) continue
|
|
409
|
+
if (TERMINAL.has(u.status)) continue
|
|
388
410
|
const since = Date.parse(u.workerSince ?? '')
|
|
389
411
|
if (!Number.isFinite(since)) continue
|
|
390
412
|
const last = Math.max(since, activity[String(u.id)] ?? 0)
|
|
@@ -610,7 +632,7 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
610
632
|
}
|
|
611
633
|
const SYNC = ['drop-unit', 'add-unit', 'set-deps', 'move-link', 'blocked-outside', 'cycle']
|
|
612
634
|
for (const a of sync?.actions ?? []) actions.push({ action: a.action, unit: a.unit, detail: a.detail })
|
|
613
|
-
const order = [...SYNC, 'worker-kind', 'decide', 'split', 'unblock', 'check-worker', 'restack', 'carry', 'review-verdict', 'start-fix', 'start-review', 'deliver', 'open-pr', 'resume', 'fill-slot']
|
|
635
|
+
const order = [...SYNC, 'worker-kind', 'decide', 'split', 'unblock', 'check-worker', 'cleanup-workspace', 'restack', 'carry', 'review-verdict', 'start-fix', 'start-review', 'deliver', 'open-pr', 'resume', 'fill-slot']
|
|
614
636
|
actions.sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action))
|
|
615
637
|
// One restack per unit per pass: the first reason found; the next pass sees the new HEAD.
|
|
616
638
|
const restacked = new Set()
|
|
@@ -625,7 +647,18 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
625
647
|
const waiting = []
|
|
626
648
|
for (const a of actions) {
|
|
627
649
|
if (!NEEDS_SLOT.has(a.action)) { due.push(a); continue }
|
|
628
|
-
if (free > 0) {
|
|
650
|
+
if (free > 0) {
|
|
651
|
+
const u = byId.get(a.unit)
|
|
652
|
+
const reviewReady = a.action !== 'start-review' || u.lifecycle?.resources?.some((r) => r.role === 'review' && r.state === 'ready')
|
|
653
|
+
const needsPreparation = managed(u) && (u.lifecycle?.workspace?.state !== 'ready' || !reviewReady)
|
|
654
|
+
const removalPending = managed(u) && u.lifecycle?.cleanup?.state === 'applying'
|
|
655
|
+
const admitted = removalPending ? { action: 'recover-workspace', unit: a.unit,
|
|
656
|
+
detail: `before ${a.action} for unit ${a.unit}, resolve its applying cleanup: inspect cleanup-runs.mjs recover --repo <repo-root> --json, collect any running cleanup operation's terminal result, and verify its receipt and every owned resource before updating lifecycle. Never admit a worker while removal of its environment is unresolved` }
|
|
657
|
+
: needsPreparation ? { action: 'prepare-workspace', unit: a.unit,
|
|
658
|
+
detail: `before ${a.action} for unit ${a.unit}, record its exact workspace, branch, base SHA and lifecycle preparation intent${reviewReady ? '' : ', including its one review clone'}; run cleanup-runs.mjs prepare --run <run> --unit ${a.unit} --revision <saved planRevision> --apply --json and persist its returned ready identity. Reuse an existing matching workspace; never reset, replace or create another one on retry` } : a
|
|
659
|
+
due.push(unlimited ? { ...admitted, detail: `${admitted.detail} [needs a free worker slot]` } : admitted)
|
|
660
|
+
free--
|
|
661
|
+
} else waiting.push(a)
|
|
629
662
|
}
|
|
630
663
|
if (native) oneChange(due)
|
|
631
664
|
const treeChanged = (sync?.actions ?? []).length > 0
|
|
@@ -645,7 +678,8 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
645
678
|
const parked = units.filter(notStarted).map((u) => `${u.id} (waits on ${waitsOn(u)})`)
|
|
646
679
|
const built = units.filter((u) => builtWaiting(u) && !u.pr).map((u) => `${u.id} (waits on ${waitsOn(u)})`)
|
|
647
680
|
const openWaiting = units.filter((u) => builtWaiting(u) && u.pr).map((u) => `${u.id} (${u.pr}, waits on ${waitsOn(u)})`)
|
|
648
|
-
|
|
681
|
+
const cleanupPending = due.some((a) => a.action === 'cleanup-workspace')
|
|
682
|
+
if (!ready.length && !cleanupPending && units.every((u) => !hasWorker(u) && (TERMINAL.has(u.status) || notStarted(u) || builtWaiting(u)) && settledBlock(u) && !sizeHeld(u) && !deciding(u)) && !treeChanged) {
|
|
649
683
|
if (sync?.fetchError) due.push({ action: 'sync', unit: null, detail: `every unit is settled, but the issue tree could not be read (${sync.fetchError.map((e) => e.error).join('; ')}): rerun with --sync until it reads; never finish on a tree you could not read` })
|
|
650
684
|
else if (sync && !String(sync.source).startsWith('live')) due.push({ action: 'sync', unit: null, detail: 'every unit is settled: rerun with --sync to check the issue tree for new issues before finishing' })
|
|
651
685
|
else if (retryable.some((u) => !u.blockedAt || !Number.isFinite(now))) {
|
|
@@ -653,7 +687,10 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
|
|
|
653
687
|
} else if (retryable.length) {
|
|
654
688
|
const next = retryable.reduce((a, u) => (dueAt(u) < dueAt(a) ? u : a))
|
|
655
689
|
due.push({ action: 'wait', unit: String(next.id), detail: `unit ${next.id} is blocked (${next.blockedReason}); its next automatic attempt is at ${new Date(dueAt(next)).toISOString()}: keep a heartbeat until then and do not finish` })
|
|
656
|
-
} else
|
|
690
|
+
} else {
|
|
691
|
+
const retained = units.filter((u) => managed(u) && u.lifecycle?.cleanup?.state === 'retained').map((u) => `${u.id}: ${u.lifecycle.cleanup.reason}`)
|
|
692
|
+
due.push({ action: 'finish', unit: null, detail: `every unit is delivered, blocked, cancelled, or not started behind one of those: write the handoff${parked.length ? `; not started: ${parked.join(', ')}` : ''}${built.length ? `; built, PR not opened: ${built.join(', ')}` : ''}${openWaiting.length ? `; PR open, cannot land: ${openWaiting.join(', ')}` : ''}${retained.length ? `; retained environments (not cleaned): ${retained.join('; ')}` : ''}` })
|
|
693
|
+
}
|
|
657
694
|
}
|
|
658
695
|
// How long each due action has gone undone, from when it was first printed.
|
|
659
696
|
const nextSeen = {}
|
|
@@ -823,7 +860,7 @@ if (isMainModule(import.meta.url)) {
|
|
|
823
860
|
if (opts.json) process.stdout.write(`${JSON.stringify({ ...result, mode, exitDue }, null, 2)}\n`)
|
|
824
861
|
else if (mode !== 'full') {
|
|
825
862
|
const view = narrowView(plan, result)
|
|
826
|
-
const guardNames = [...new Set(result.due.filter((a) => /^guards: (?!none)/m.test(view) && ['decide', 'review-verdict', 'unblock', 'worker-kind', 'split', 'sync', 'add-unit', 'drop-unit', 'set-deps', 'move-link', 'blocked-outside'].includes(a.action)).map((a) => a.action))]
|
|
863
|
+
const guardNames = [...new Set(result.due.filter((a) => /^guards: (?!none)/m.test(view) && ['recover-workspace', 'prepare-workspace', 'cleanup-workspace', 'decide', 'review-verdict', 'unblock', 'worker-kind', 'split', 'sync', 'add-unit', 'drop-unit', 'set-deps', 'move-link', 'blocked-outside'].includes(a.action)).map((a) => a.action))]
|
|
827
864
|
process.stdout.write(`${mode === 'off' ? `${view.split('\n')[0].replace(/: .*$/, '')}${guardNames.length ? ` (clear first: ${guardNames.join(', ')})` : ''}` : view}\n`)
|
|
828
865
|
process.stdout.write(`${budgetLine(result.capacity)}\n`)
|
|
829
866
|
process.stdout.write(rulesLine(`${mode === 'off' ? 'Scheduler mode off: plan every step yourself from the plan and results.' : 'Scheduler mode narrow: clear the guards, then choose each unit\'s next step yourself.'} The run ends only when this prints "run done".`))
|
|
@@ -843,7 +880,7 @@ if (isMainModule(import.meta.url)) {
|
|
|
843
880
|
// The narrow view: whether the run is done, which units have work, the guards, and what waits on
|
|
844
881
|
// the human. It leaves each unit's next step to the coordinator.
|
|
845
882
|
export function narrowView(plan, result) {
|
|
846
|
-
const GUARDS = new Set(['decide', 'review-verdict', 'unblock', 'worker-kind', 'split', 'sync', 'add-unit', 'drop-unit', 'set-deps', 'move-link', 'blocked-outside'])
|
|
883
|
+
const GUARDS = new Set(['recover-workspace', 'prepare-workspace', 'cleanup-workspace', 'decide', 'review-verdict', 'unblock', 'worker-kind', 'split', 'sync', 'add-unit', 'drop-unit', 'set-deps', 'move-link', 'blocked-outside'])
|
|
847
884
|
const units = new Map((plan.units ?? []).map((u) => [String(u.id), u]))
|
|
848
885
|
const guards = result.due.filter((a) => GUARDS.has(a.action)).map((a) => `${a.unit ?? 'run'}: ${a.detail}`)
|
|
849
886
|
const work = [...new Set([...result.due, ...result.waiting].filter((a) => a.unit && !GUARDS.has(a.action) && a.action !== 'wait').map((a) => a.unit))]
|
|
@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url'
|
|
|
22
22
|
|
|
23
23
|
import { workerResources } from '../../engineering-runtime/scripts/installation-resolver.mjs'
|
|
24
24
|
import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
|
|
25
|
-
import { RULES, SKILL_PATH } from './next-actions.mjs'
|
|
25
|
+
import { RULES, RUN_SKILLS, SKILL_PATH, workspaceCleanupSettled } from './next-actions.mjs'
|
|
26
26
|
|
|
27
27
|
export const ACTIVE_HOURS = 24
|
|
28
28
|
const SCRIPTS = dirname(fileURLToPath(import.meta.url))
|
|
@@ -52,6 +52,7 @@ export function activeRuns(cwd, now = Date.now(), hours = ACTIVE_HOURS) {
|
|
|
52
52
|
if (now - mtime > hours * 3_600_000) continue
|
|
53
53
|
let plan
|
|
54
54
|
try { plan = JSON.parse(readFileSync(file, 'utf8')) } catch { continue }
|
|
55
|
+
if (plan.skill !== undefined && !RUN_SKILLS.includes(plan.skill)) continue
|
|
55
56
|
const units = (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
|
|
56
57
|
const open = units.filter((u) => !DONE.has(u?.status)).length
|
|
57
58
|
if (!open) continue
|
|
@@ -61,6 +62,39 @@ export function activeRuns(cwd, now = Date.now(), hours = ACTIVE_HOURS) {
|
|
|
61
62
|
return runs.sort((a, b) => b.mtime - a.mtime).map(({ mtime, ...r }) => r)
|
|
62
63
|
}
|
|
63
64
|
|
|
65
|
+
// Recovery discovery must not activate a workflow, and has no age cutoff.
|
|
66
|
+
export function cleanupRuns(cwd) {
|
|
67
|
+
const root = runsRoot(cwd)
|
|
68
|
+
if (!root) return []
|
|
69
|
+
let names
|
|
70
|
+
try { names = readdirSync(root) } catch { return [] }
|
|
71
|
+
const out = []
|
|
72
|
+
for (const name of names) {
|
|
73
|
+
const dir = join(root, name)
|
|
74
|
+
let plan
|
|
75
|
+
try { plan = JSON.parse(readFileSync(join(dir, 'task-plan.json'), 'utf8')) } catch { continue }
|
|
76
|
+
if (Array.isArray(plan.units) && Array.isArray(plan.issues) && JSON.stringify(plan.units) !== JSON.stringify(plan.issues)) {
|
|
77
|
+
out.push({ dir, units: [], reason: 'conflicting units and issues rosters; ownership requires reconciliation' })
|
|
78
|
+
continue
|
|
79
|
+
}
|
|
80
|
+
const units = Array.isArray(plan.units) ? plan.units : plan.issues
|
|
81
|
+
if (!Array.isArray(units)) continue
|
|
82
|
+
const pending = units.filter((u) => u.status === 'succeeded' && u.delivery === 'merged' && u.workspace && !workspaceCleanupSettled(u))
|
|
83
|
+
if (pending.length) out.push({ dir, units: pending.map((u) => String(u.id)),
|
|
84
|
+
...(pending.some((u) => plan.workspaceLifecycle !== 1 && u.lifecycle?.version !== 1) ? { reason: 'legacy workspace ownership is unresolved; inventory only, never automatic adoption or deletion' } : {}) })
|
|
85
|
+
}
|
|
86
|
+
return out.sort((a, b) => a.dir.localeCompare(b.dir))
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export function cleanupMessage(runs) {
|
|
90
|
+
if (!runs.length) return ''
|
|
91
|
+
return [
|
|
92
|
+
'Read-only recovery notice: these delivered units still have pending or interrupted workspace cleanup:',
|
|
93
|
+
...runs.map((r) => `- ${r.dir}: ${r.units.join(', ') || 'ownership unresolved'}${r.reason ? ` (${r.reason})` : ''}`),
|
|
94
|
+
'This notice does not activate a workflow or authorize deletion. When the owning work resumes, inspect cleanup-runs.mjs recover --repo <owning repo> --json, then use its recorded ownership and current revision. Never infer completed cleanup from age or an absent path.',
|
|
95
|
+
].join('\n')
|
|
96
|
+
}
|
|
97
|
+
|
|
64
98
|
export function message(runs, { skillPath = SKILL_PATH, rushSkillPath = RUSH_SKILL_PATH } = {}) {
|
|
65
99
|
if (!runs.length) return ''
|
|
66
100
|
if (runs.some((run) => run.installation)) {
|
|
@@ -103,7 +137,7 @@ export function main(argv) {
|
|
|
103
137
|
if (hook) {
|
|
104
138
|
try { cwd = JSON.parse(readFileSync(0, 'utf8'))?.cwd || cwd } catch { /* no input: keep cwd */ }
|
|
105
139
|
}
|
|
106
|
-
const text = message(activeRuns(cwd))
|
|
140
|
+
const text = [message(activeRuns(cwd)), cleanupMessage(cleanupRuns(cwd))].filter(Boolean).join('\n\n')
|
|
107
141
|
if (text) process.stdout.write(hook ? `${hookOutput(text)}\n` : `${text}\n`)
|
|
108
142
|
} catch (error) {
|
|
109
143
|
process.stderr.write(`rehydrate: ${error.message}\n`)
|
|
@@ -32,15 +32,16 @@
|
|
|
32
32
|
// the fix worker's whole finding list. `action` says how to fix, from a
|
|
33
33
|
// comparison with the previous round's file (`<unit>-r<N-1>.json` beside
|
|
34
34
|
// it, or --prior):
|
|
35
|
-
// fix first blocking round: fix each finding's rule
|
|
36
|
-
//
|
|
35
|
+
// fix first blocking round: fix each finding's rule across its
|
|
36
|
+
// applicable paths and close every row
|
|
37
37
|
// test-first a P0/P1 came back after a fix: name the rule it breaks,
|
|
38
|
-
// list
|
|
39
|
-
//
|
|
38
|
+
// list the applicable paths, reuse sufficient tests and add
|
|
39
|
+
// focused cases for missing proof, see the open cases fail,
|
|
40
|
+
// then fix until all pass, with the
|
|
40
41
|
// escalation model
|
|
41
42
|
// one-by-one only new P0/P1, introduced by the last fix: one finding
|
|
42
43
|
// per fix worker, in turn, the smallest change that closes
|
|
43
|
-
// every row
|
|
44
|
+
// every row across the applicable paths
|
|
44
45
|
// 5 wait: no P0/P1 is open, but a GitHub reviewer whose changes request a fix brief
|
|
45
46
|
// already carried has not re-reviewed (`awaiting`, from github-reviews.mjs merge);
|
|
46
47
|
// request their re-review and run the merge and this verdict again when it lands
|
|
@@ -332,9 +333,9 @@ export function carryRecord(prior, head, identity = {}) {
|
|
|
332
333
|
}
|
|
333
334
|
|
|
334
335
|
const INSTRUCTIONS = {
|
|
335
|
-
'fix': 'Fix only these findings. For each, fix its `rule`
|
|
336
|
-
'test-first': 'The findings listed in `recurring` survived a fix: the last fix closed one path and missed others. For each, before changing code: name the rule the bug breaks; list every code path that can break it, including the trigger of this finding id in each earlier round\'s review file beside this one;
|
|
337
|
-
'one-by-one': 'The last fix introduced these findings. Fix them one at a time, one fix worker each, with the smallest change that closes every row of its `paths
|
|
336
|
+
'fix': 'Fix only these findings. For each, make the smallest complete fix for its `rule` across the applicable paths and close every row in its `paths`. Use a shared owner when useful, but do not require a refactor; focused fixes on individual paths are acceptable.',
|
|
337
|
+
'test-first': 'The findings listed in `recurring` survived a fix: the last fix closed one path and missed others. For each, before changing code: name the rule the bug breaks; list every code path that can break it, including the trigger of this finding id in each earlier round\'s review file beside this one; reuse sufficient tests and add focused cases from the concrete triggers, then run them to see it fail on each open path. One table-driven test may cover several paths. Then make the smallest complete fix across the applicable paths until every test passes. Use a shared owner when useful, but do not require a refactor; focused fixes on individual paths are acceptable. "Fixed" is every path\'s test passing. Fix the rest as usual.',
|
|
338
|
+
'one-by-one': 'The last fix introduced these findings. Fix them one at a time, one fix worker each, with the smallest complete change that closes every row of its `paths`. Use a shared owner when useful, but do not require a refactor; focused fixes on individual paths are acceptable. Touch nothing else.',
|
|
338
339
|
}
|
|
339
340
|
|
|
340
341
|
// The fix worker's brief carries only P0/P1 findings; P2/P3 never reach it.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '../../harness-runtime/workspace-lifecycle.mjs'
|
|
@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
|
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
metadata:
|
|
6
6
|
workflow-role: coordinator
|
|
7
|
-
release-version: 0.
|
|
7
|
+
release-version: 0.45.0
|
|
8
8
|
---
|
|
9
9
|
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
10
10
|
# Resolve release
|
|
@@ -6,7 +6,7 @@ metadata:
|
|
|
6
6
|
workflow-role: coordinator
|
|
7
7
|
dependencies:
|
|
8
8
|
- resolve-issues
|
|
9
|
-
release-version: 0.
|
|
9
|
+
release-version: 0.45.0
|
|
10
10
|
---
|
|
11
11
|
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
12
12
|
# Rush issues (shortcut of resolve-issues)
|
|
@@ -55,7 +55,9 @@ question.
|
|
|
55
55
|
mode too: keep one immediate checkpoint per active unit, justify infrastructure and
|
|
56
56
|
reassess repeated non-convergence. More worker activity is not a reason to reset it.
|
|
57
57
|
The shared [task-plan checkpoints](../resolve-issues/references/task-plan.md#checkpoints)
|
|
58
|
-
apply too:
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
apply too: when `update_todo` is advertised, capture the known outcome before
|
|
59
|
+
substantive work, then bind or reload with the absolute workflow path and
|
|
60
|
+
persisted revision. No event means the plan is read-only; save transitions
|
|
61
|
+
through its `workflow` payload. Never edit a bound plan directly. When the
|
|
62
|
+
optional tool is absent or disabled, use the workflow's file transition; never
|
|
63
|
+
enable the interface as a precondition.
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: test-quality
|
|
3
3
|
description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
|
|
4
|
-
release-version: 0.
|
|
4
|
+
release-version: 0.45.0
|
|
5
5
|
---
|
|
6
6
|
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
7
7
|
# Test Quality
|
|
8
8
|
|
|
9
9
|
A test is worth keeping when it fails for a real bug and stays green through a harmless change. This skill states seven principles that decide that and audits a suite against them. Each principle's examples, common failures, and look-alikes: [references/principles.md](references/principles.md).
|
|
10
10
|
|
|
11
|
-
- **Write mode**:
|
|
11
|
+
- **Write mode**: judge the tests needed for the requested behavior using the principles and the one question. Run `node "$SKILL_DIR/scripts/lint-tests.mjs" --diff <base>` when requested or required by the repository ([lint](#the-lint)); it covers uncommitted and untracked tests. An optional lint result does not create a new acceptance gate.
|
|
12
12
|
- **Audit mode**: reviewer subagents sweep a suite or a diff and report findings, quick by default ([audit](#audit-mode)). The audit **never edits, rewrites, or deletes a test**. It names the principle broken and the evidence; the fix belongs to the implementer.
|
|
13
13
|
- **Persist mode**: only when the user asks, write the principles into the repo's `CONTRIBUTING.md` ([persist](#persist-mode)).
|
|
14
14
|
|
|
@@ -22,6 +22,21 @@ A test is worth keeping when it fails for a real bug and stays green through a h
|
|
|
22
22
|
| 6 | [Don't test config files](references/principles.md#6-dont-test-config-files) | Restating a config file in a test | a Dockerfile, workflow, `cloudbuild.yaml`, `.mergify.yml`, `package.json`, or other JSON/YAML/TOML config read, then any assertion |
|
|
23
23
|
| 7 | [Same code, same result](references/principles.md#7-same-code-same-result) | A result that depends on luck | `Math.random`/`uuid()`/`Date.now()` in checked output; `sleep(…)`; passes in the suite, fails alone; scratch files under the repo or `cwd` |
|
|
24
24
|
|
|
25
|
+
## Scope while writing
|
|
26
|
+
|
|
27
|
+
Use these principles to judge the tests the task needs, not to start a suite-wide
|
|
28
|
+
cleanup. First identify the requested behavior or concrete regression and reuse
|
|
29
|
+
existing tests that prove it. Add focused assertions at the lowest level that
|
|
30
|
+
observes the real outcome; do not automatically duplicate them across test layers.
|
|
31
|
+
|
|
32
|
+
Before testing a defensive branch, check that its behavior belongs to the supported
|
|
33
|
+
contract. A new guard or fallback does not create its own testing requirement.
|
|
34
|
+
Speculative failures, coverage percentages, and test counts do not justify expanding
|
|
35
|
+
a feature into a harness, framework, or gate project. Keep binding checks and material
|
|
36
|
+
security, money, tenancy, and data-integrity proof; report unrelated debt rather than
|
|
37
|
+
fixing it. Stop once the agreed behavior is sufficiently proven. Broad audits and
|
|
38
|
+
convention persistence remain separate, explicitly requested tasks.
|
|
39
|
+
|
|
25
40
|
## The one question
|
|
26
41
|
|
|
27
42
|
For every assertion, answer both halves:
|
|
@@ -35,7 +50,7 @@ A good assertion has a concrete answer to (1) and none to (2). An assertion with
|
|
|
35
50
|
|
|
36
51
|
1. **Test behavior, not text.** Run the code and observe what it does. The text of a doc, prompt, source file, or migration is not behavior. A test whose only assertions are text matches over checked-in files is **`Not coverage`** for the behavior the text describes, never partial proof.
|
|
37
52
|
2. **The expected value comes from somewhere other than the code under test.** Take it from the spec, an external contract, a separately written simpler model, or the input: never from the code under test or a literal copied out of it. When a version really is the contract, pin the major only.
|
|
38
|
-
3. **Fake only what you don't own.**
|
|
53
|
+
3. **Fake only what you don't own for boundary proof.** Use real database and service behavior when proving transactions, tenant filters, locking, or idempotency; fake external providers, clock, and randomness. A focused unit test may isolate an internal collaborator, but proves only behavior it actually executes. An over-mocked test is `Not coverage` for the behavior the fake hides. Follow stricter adopted repo rules where required.
|
|
39
54
|
4. **An assertion must be able to fail.** Every test can go red and checks what its name promises: read the name's verbs ("atomically", "then", "corrected to") and find the assertion for each.
|
|
40
55
|
5. **Test each behavior once, and only for code that still runs.** Prove each behavior once, at the lowest level that proves it for real. Layering (a pure unit for the decision table plus one real-DB test per rule) is not duplication; many similar cases merge into a table rather than being deleted.
|
|
41
56
|
6. **Don't test config files.** Dockerfiles, `cloudbuild.yaml`, `.github/workflows/*`, `.mergify.yml`, `package.json`, `tsconfig.json`, `pyproject.toml`, `.env`, and any other JSON, YAML, or TOML a tool reads get no tests: the tool that reads the file is the test. Test the code that reads config; run scripts, because scripts are code. A pin added after a real bug is still a config test: delete it and name the missing behavior check as a follow-up. JSON the app loads as data (locales, price tables) is not config.
|
|
@@ -69,7 +84,7 @@ It writes the seven principles ([references/testing-conventions.md](references/t
|
|
|
69
84
|
|
|
70
85
|
## The lint
|
|
71
86
|
|
|
72
|
-
Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file from, never your CWD. `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` only lines changed since the merge-base. A **gate** rule
|
|
87
|
+
Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file from, never your CWD. `node "$SKILL_DIR/scripts/lint-tests.mjs"` scans the tree; `--diff <base>` only lines changed since the merge-base. A tool-local **gate** rule fails the command's exit status; it is not automatically a repository merge requirement. Assess optional hits in context and preserve existing adopted gates. Rules, flags, and what a clean run proves (little, for Python and Go): [references/lint.md](references/lint.md).
|
|
73
88
|
|
|
74
89
|
## Common wrong answers
|
|
75
90
|
|
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
Scripts live under **this skill's directory**. Set `SKILL_DIR` to the directory you read this file from and run `node "$SKILL_DIR/scripts/lint-tests.mjs"`. Never resolve against your CWD. A missing script in the audited repo is not a blocker; the scripts belong to this skill.
|
|
6
6
|
|
|
7
|
-
A **gate** rule
|
|
7
|
+
A tool-local **gate** rule fails the command's exit status; a **lead** rule reports a pattern for inspection. Run this optional tool when requested or required by the repository, scoped to the task. Its classifier detects syntax, not whether a test proves its claimed behavior. An optional hit does not create a new merge requirement or require replacing valid unit isolation with infrastructure. Preserve adopted repo gates and report their actual failures; changing those gates requires approval.
|
|
8
8
|
|
|
9
9
|
| rule | principle | severity | finds |
|
|
10
10
|
|---|---|---|---|
|
|
@@ -49,14 +49,14 @@
|
|
|
49
49
|
|
|
50
50
|
## 3. Fake only what you don't own
|
|
51
51
|
|
|
52
|
-
**Principle.**
|
|
52
|
+
**Principle.** For proof of a real boundary, use real internals and fake externals: third-party APIs, providers, clock, and randomness. A fake database cannot prove transactions, tenant filters, locking, or idempotency. A focused unit test may isolate an internal collaborator to exercise the caller's own decision logic; it does not prove the collaborator's behavior. Existing stricter repo rules remain binding.
|
|
53
53
|
|
|
54
54
|
**Done right.**
|
|
55
55
|
- Real Postgres with migrations; only the payment provider faked.
|
|
56
56
|
- A spy at an external boundary where **the call is the behavior**: the backoff delay, the precondition header sent to storage, "the provider was not called after validation failed".
|
|
57
57
|
|
|
58
58
|
**Common failures.**
|
|
59
|
-
- *First-party mock:* `vi.mock('@/lib/prisma')
|
|
59
|
+
- *First-party mock counted as boundary proof:* `vi.mock('@/lib/prisma')` cannot prove real persistence; patching a private helper cannot prove the code replaced. The `mock-internal-seam` scanner flags the JS module form, but an optional hit needs this semantic check. Your own thin adapter around a provider (`@/lib/stripe-client`) is the external boundary; declare it in `coverage.config.json` under `mockPolicy.externals` where the repo uses that topology.
|
|
60
60
|
- *Blind injected fake:* a `deps` fake returns rows whatever the query says, and the test asserts `findUnique({ where: { id } })`. Delete the tenant check and it stays green. No rule sees `deps` injection; read for it.
|
|
61
61
|
- *Mocked transaction:* "updates atomically" with `$transaction: (fn) => fn()`.
|
|
62
62
|
- *Layout in jsdom:* `toHaveClass('min-h-11')` to prove a 44px target. jsdom has no layout.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
1. Run the code and assert what it does; never match the text of docs, prompts, source files, or migrations.
|
|
4
4
|
2. Take expected values from the spec, an external contract, or the input, never from the code under test; pin versions to the major only.
|
|
5
|
-
3.
|
|
5
|
+
3. Prove transactions, tenant filters, locking, and idempotency against real database and service behavior; fake external providers, the clock, and randomness. Internal unit-test substitutes prove only the caller behavior they execute, not the replaced boundary. Preserve stricter adopted repository requirements.
|
|
6
6
|
4. Make every assertion able to fail, and assert everything the test name promises.
|
|
7
7
|
5. Test each behavior once, at the lowest level that proves it; delete tests of dead code.
|
|
8
8
|
6. Don't test config files (Dockerfiles, CI workflows, `cloudbuild.yaml`, merge-queue config, `package.json`, other JSON/YAML/TOML a tool reads); test the code that reads them.
|
|
@@ -1,70 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: contributing
|
|
3
|
-
description: "The conventions a repo's CONTRIBUTING.md holds, starting with tracker routing: which tracker an issue belongs in (GitHub for engineering, Linear for product), duplicate search, and linking back to the source requirement. Use before creating any issue, spec, epic, ticket or sub-issue on GitHub or Linear, including inside /to-spec, /to-tickets and /triage, and whenever work that started from a Linear issue turns into engineering work. Also writes the rules as the Issue tracking section of the repo's CONTRIBUTING.md. NOT for delivering a PR (github-flow) or splitting work into slices (to-tickets)."
|
|
4
|
-
release-version: 0.44.1
|
|
5
|
-
---
|
|
6
|
-
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
7
|
-
# Contributing
|
|
8
|
-
|
|
9
|
-
Rules every engineering skill follows, whatever skill or harness is running, kept as sections of the
|
|
10
|
-
repo's `CONTRIBUTING.md`. Each rule is the authority; another skill's "publish to the configured
|
|
11
|
-
tracker" means the tracker these rules pick.
|
|
12
|
-
|
|
13
|
-
## First use in a repo
|
|
14
|
-
|
|
15
|
-
Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file
|
|
16
|
-
from, never your CWD. On the first trigger in a repo, write the `## Issue tracking` section into its
|
|
17
|
-
`CONTRIBUTING.md`, creating the file when it is missing:
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <repo-root> --if-missing --write \
|
|
21
|
-
[--linear-project "<Linear project>"]... [--github-repo <owner/name>]
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
- **Pass every Linear project whose resources link to this repo.** Example: the `Checkout Risk`
|
|
25
|
-
project lists `https://github.com/acme/widgets`, so pass `--linear-project "Checkout Risk"`.
|
|
26
|
-
- **Pass `--github-repo` only when `origin` is not the GitHub repo.** Example: exit 2 with
|
|
27
|
-
`no GitHub origin remote` means pass it.
|
|
28
|
-
- **`--if-missing` never touches an existing section.** To rewrite it, run without `--if-missing`.
|
|
29
|
-
- **`AGENTS.md` indexes `CONTRIBUTING.md`.** The script adds a `## Contributing` pointer unless
|
|
30
|
-
`AGENTS.md` already names `CONTRIBUTING.md`, creates a missing `AGENTS.md`, and creates a missing
|
|
31
|
-
`CLAUDE.md` as a symlink to `AGENTS.md`, even when the section already exists.
|
|
32
|
-
- Report each file's result line; commit with the change you are making, or leave it for the user
|
|
33
|
-
when you make no other change.
|
|
34
|
-
|
|
35
|
-
## Tracker routing
|
|
36
|
-
|
|
37
|
-
| Work item | Tracker |
|
|
38
|
-
|---|---|
|
|
39
|
-
| Product goals, business requirements, priorities, milestones | Linear |
|
|
40
|
-
| Consulting engagements, reports, research deliverables | Linear |
|
|
41
|
-
| Engineering specs and implementation epics | GitHub |
|
|
42
|
-
| Implementation tickets, technical investigations, refactors, engineering bugs | GitHub |
|
|
43
|
-
| Delivery progress for stakeholders | A summary in Linear that links to GitHub |
|
|
44
|
-
|
|
45
|
-
Before you create an issue:
|
|
46
|
-
|
|
47
|
-
1. **Classify the work; the tracker follows the work, not where the request came from.** Example:
|
|
48
|
-
`/to-spec` run on a conversation about DEV-123 publishes a GitHub issue.
|
|
49
|
-
2. **Resolve the GitHub repo in this order: the repo's `CONTRIBUTING.md` Issue tracking section, the
|
|
50
|
-
GitHub links in the source Linear project's resources, then ask the user. Never fall back to
|
|
51
|
-
Linear.** Example: a project linking two repos gets the repo the work changes; a project linking
|
|
52
|
-
none gets a question, not a Linear ticket.
|
|
53
|
-
3. **Search before you create.** Example: `gh issue list --repo <owner/name> --state all --search
|
|
54
|
-
"<keywords>"`; reuse or comment on a match.
|
|
55
|
-
4. **A Linear issue is a source reference, never a parent for implementation tickets.** Example: put
|
|
56
|
-
`Source: <Linear URL>` in the GitHub epic body and file the tickets as GitHub sub-issues of the
|
|
57
|
-
epic.
|
|
58
|
-
5. **Link back once per epic.** Example: add the GitHub epic URL to the Linear requirement as a
|
|
59
|
-
link; never copy the GitHub tickets into Linear.
|
|
60
|
-
6. **Report progress in Linear as a summary; acceptance stays with the requester.** Example: when the
|
|
61
|
-
last sub-issue closes, comment `Engineering complete: <epic URL>` on the Linear requirement and
|
|
62
|
-
leave its status alone.
|
|
63
|
-
7. **An explicit destination from the user wins.** Example: "file this in Linear" files it in Linear.
|
|
64
|
-
|
|
65
|
-
## Common wrong answers
|
|
66
|
-
|
|
67
|
-
- "The request came from Linear, so the tickets go in Linear." The work type decides, rule 1.
|
|
68
|
-
- "No tracker is configured, so use the one the conversation used." Resolve the repo, rule 2.
|
|
69
|
-
- "Mirror the epic into Linear so stakeholders see it." Post a summary with a link, rule 5.
|
|
70
|
-
- "All sub-issues closed, so the Linear requirement is done." Engineering complete is not accepted, rule 6.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|