@1aboveio/engineering-skills 0.1.9 → 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.
Files changed (66) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/skills/better-review/SKILL.md +37 -37
  4. package/skills/better-review/references/passes.md +35 -41
  5. package/skills/better-review/references/result.md +10 -9
  6. package/skills/e2e-test/SKILL.md +17 -17
  7. package/skills/e2e-test/references/authoring/playwright-config.md +11 -13
  8. package/skills/e2e-test/references/presentation-sweep.md +7 -7
  9. package/skills/e2e-test/references/reviewing.md +9 -11
  10. package/skills/e2e-test/references/route-manifest.md +1 -1
  11. package/skills/engineering/SKILL.md +124 -0
  12. package/skills/engineering/references/engineering-conventions.md +32 -0
  13. package/skills/engineering/references/feature-delivery.md +8 -0
  14. package/skills/engineering/references/init-scope.md +37 -0
  15. package/skills/engineering/scripts/init.mjs +160 -0
  16. package/skills/{contributing → engineering}/scripts/persist-conventions.mjs +1 -1
  17. package/skills/engineering-runtime/SKILL.md +1 -1
  18. package/skills/engineering-runtime/coherence/workflow.json +19 -19
  19. package/skills/engineering-runtime/scripts/workflow-policy.mjs +1 -1
  20. package/skills/ensure-coverage/SKILL.md +22 -109
  21. package/skills/ensure-coverage/references/breadth/coverage-ledger.md +7 -5
  22. package/skills/ensure-coverage/references/breadth/surface-baseline.md +4 -4
  23. package/skills/ensure-coverage/references/breadth/surface-discovery.md +3 -3
  24. package/skills/ensure-coverage/references/depth/characterization.md +4 -65
  25. package/skills/ensure-coverage/references/depth/grading.md +5 -7
  26. package/skills/ensure-coverage/references/depth/mock-policy.md +6 -12
  27. package/skills/ensure-coverage/references/enforcement/ci-contract.md +1 -1
  28. package/skills/ensure-coverage/references/presentation/axis.md +6 -6
  29. package/skills/ensure-coverage/references/process/audit-mode.md +7 -23
  30. package/skills/ensure-coverage/references/process/output-template.md +18 -133
  31. package/skills/ensure-coverage/references/process/test-strategy.md +7 -12
  32. package/skills/ensure-coverage/scripts/README.md +12 -4
  33. package/skills/golden-path/SKILL.md +1 -1
  34. package/skills/harness-runtime/SKILL.md +3 -1
  35. package/skills/harness-runtime/bin/workspaces.mjs +52 -0
  36. package/skills/harness-runtime/native-workspace.mjs +239 -0
  37. package/skills/harness-runtime/references/workspaces.md +78 -0
  38. package/skills/harness-runtime/workspace-lifecycle.mjs +2154 -0
  39. package/skills/resolve-issues/SKILL.md +40 -61
  40. package/skills/resolve-issues/references/ci.md +13 -3
  41. package/skills/resolve-issues/references/delivery-progress.md +4 -3
  42. package/skills/resolve-issues/references/done.md +11 -2
  43. package/skills/resolve-issues/references/expire.md +9 -2
  44. package/skills/resolve-issues/references/implementation.md +33 -17
  45. package/skills/resolve-issues/references/preflight.md +3 -1
  46. package/skills/resolve-issues/references/principles.md +52 -0
  47. package/skills/resolve-issues/references/review.md +25 -15
  48. package/skills/resolve-issues/references/task-plan.md +64 -27
  49. package/skills/resolve-issues/references/workspaces.md +164 -0
  50. package/skills/resolve-issues/scripts/cleanup-runs.mjs +185 -317
  51. package/skills/resolve-issues/scripts/next-actions.mjs +44 -7
  52. package/skills/resolve-issues/scripts/rehydrate.mjs +36 -2
  53. package/skills/resolve-issues/scripts/review-verdict.mjs +9 -8
  54. package/skills/resolve-issues/scripts/workspace-lifecycle.mjs +1 -0
  55. package/skills/resolve-release/SKILL.md +1 -1
  56. package/skills/rush-issues/SKILL.md +7 -5
  57. package/skills/rush-release/SKILL.md +1 -1
  58. package/skills/test-quality/SKILL.md +19 -4
  59. package/skills/test-quality/references/lint.md +1 -1
  60. package/skills/test-quality/references/principles.md +2 -2
  61. package/skills/test-quality/references/testing-conventions.md +1 -1
  62. package/skills/contributing/SKILL.md +0 -70
  63. /package/skills/{contributing → engineering}/LICENSE +0 -0
  64. /package/skills/{contributing → engineering}/references/tracker-conventions.md +0 -0
  65. /package/skills/{contributing → engineering}/release-check.mjs +0 -0
  66. /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 update_plan. --resume and --sync fetch the tree (one GraphQL
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) { due.push(unlimited ? { ...a, detail: `${a.detail} [needs a free worker slot]` } : a); free-- } else waiting.push(a)
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
- if (!ready.length && units.every((u) => (TERMINAL.has(u.status) || notStarted(u) || builtWaiting(u)) && settledBlock(u) && !sizeHeld(u) && !deciding(u)) && !treeChanged) {
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 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(', ')}` : ''}` })
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 at its one
36
- // owner and close every row in its paths
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 every path that can break it, test each path, see
39
- // the tests fail, then fix until all pass, with the
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 at the rule's owner
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` at the one place every path passes through, never by copying a guard to each path, and close every row in its `paths`.',
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; write a test per path from its trigger and run them: see it fail on each open path. Then fix the rule at its one owner, the place every path passes through, not path by path, until every test passes. "Fixed" is every path\'s test passing. Fix the rest as usual.',
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` at the rule\'s owner; touch nothing else.',
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.44.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.44.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: on Pi, bind or reload through `update_plan` with the absolute
59
- workflow path and persisted revision (no event means read-only), then
60
- save transitions through its `workflow` payload. The TUI refreshes
61
- automatically; never edit the bound plan directly.
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.
@@ -6,7 +6,7 @@ metadata:
6
6
  workflow-role: coordinator
7
7
  dependencies:
8
8
  - resolve-release
9
- release-version: 0.44.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 release (shortcut of resolve-release)
@@ -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.44.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**: the principles are the bar while you write or change tests. Check each new assertion against the one question, and before you commit run `node "$SKILL_DIR/scripts/lint-tests.mjs" --diff <base>` from the repo root ([lint](#the-lint)); it covers uncommitted and untracked tests.
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.** Fake third-party APIs, providers, the clock, and randomness. Your database and services run for real, because a fake cannot see transactions, tenant filters, locking, or idempotency. An over-mocked test is `Not coverage` for the behavior the fake hides.
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 is decidable and fails the exit code; a **lead** also matches legitimate tests, so read each hit against the principle's look-alikes. Rules, flags, and what a clean run proves (little, for Python and Go): [references/lint.md](references/lint.md).
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 is decidable and fails the exit code; a **lead** rule also matches some legitimate tests, so read each hit against the principle's "Not a failure" cases.
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.** Real internals, faked externals. Substitute only what you do not own: third-party APIs, providers, clock, randomness (faking the clock and randomness is also how a test stays repeatable: [principle 7](#7-same-code-same-result)). Your database and services run for real, because a fake cannot see what lives in them: transactions, tenant filters, locking, idempotency.
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')`, patching the class's own `_private` helper. The `mock-internal-seam` rule catches the JS module form. Your own thin adapter around a provider (`@/lib/stripe-client`) *is* the external boundary: declare it in `coverage.config.json` under `mockPolicy.externals` rather than calling it a finding.
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. Fake only third-party services, the clock, and randomness; run your own database and services for real.
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.0
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