@1aboveio/skills 1.0.10 → 1.0.11

package/skills/engineering/resolve-issues/scripts/next-actions.mjs

@@ -11,7 +11,7 @@
 //
 //   add-unit, drop-unit, set-deps, move-link, blocked-outside, cycle
 //                   the plan differs from the spec's GitHub issue tree (plan-sync.mjs): apply
-//                   it through update_plan. --resume and --sync fetch the tree (one GraphQL
+//                   it through the available checkpoint mechanism. --resume and --sync fetch the tree (one GraphQL
 //                   query) and save it; every other call diffs the saved tree, with no
 //                   GitHub call. Sync after the run files an issue
 //   unblock         a unit marked blocked without a reason from BLOCK_REASONS
@@ -176,6 +176,12 @@ export function normalizeCapacity(input) {
 const hasWorker = (u) => u.worker !== undefined && u.worker !== null && u.worker !== ''
 const codeDone = (u) => u.stage === 'done'
 
+export function workspaceCleanupSettled(unit) {
+  const result = unit.lifecycle?.cleanup
+  return typeof unit.headSha === 'string' && unit.headSha.length > 0 && result?.headSha === unit.headSha &&
+    (result.state === 'complete' || (result.state === 'retained' && typeof result.reason === 'string' && result.reason.trim().length > 0))
+}
+
 // Pure decision from the plan and each unit's newest review round.
 // `capacity`: a fresh Harness snapshot, or an explicitly reconciled total workflow budget.
 // Snapshot availableSlots is already net of all running and reserved workers.
@@ -191,6 +197,10 @@ const codeDone = (u) => u.stage === 'done'
 // `key` is the result file, relative to the run, that a `decisions` entry's `answers` names.
 export function nextActions(plan, reviews = {}, capacity, { resume = false, now, activity = {}, quietMinutes = DEFAULT_QUIET_MINUTES, sync = null, seen = {}, questions = {} } = {}) {
   const effectiveCapacity = normalizeCapacity(capacity)
+  if (Array.isArray(plan?.units) && Array.isArray(plan?.issues) && JSON.stringify(plan.units) !== JSON.stringify(plan.issues)) {
+    throw new NextActionsError('task plan has conflicting units and issues rosters')
+  }
+  if (plan?.workspaceLifecycle !== undefined && plan.workspaceLifecycle !== 1) throw new NextActionsError('unsupported workspaceLifecycle version')
   const saved = (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
   if (!Array.isArray(saved) || saved.length === 0) throw new NextActionsError('task plan has no units')
   const excluded = excludedIds(plan)
@@ -328,6 +338,17 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   }
   const actions = []
   const add = (action, u, detail) => actions.push({ action, unit: String(u.id), detail })
+  const managed = (u) => plan.workspaceLifecycle === 1 || u.lifecycle?.version === 1
+  for (const u of units) {
+    if (TERMINAL.has(u.status) && hasWorker(u) && (u.status !== 'blocked' || reasonOk(u))) {
+      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`)
+      continue
+    }
+    if (!managed(u) || u.status !== 'succeeded' || !u.workspace) continue
+    if (!hasWorker(u) && !workspaceCleanupSettled(u)) {
+      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`)
+    }
+  }
   const chainReady = []
   const chainOpen = (u) => {
     const id = String(u.id)
@@ -385,6 +406,7 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
     const quietMs = quietMinutes * 60_000
     for (const u of units) {
       if (!hasWorker(u)) continue
+      if (TERMINAL.has(u.status)) continue
       const since = Date.parse(u.workerSince ?? '')
       if (!Number.isFinite(since)) continue
       const last = Math.max(since, activity[String(u.id)] ?? 0)
@@ -610,7 +632,7 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   }
   const SYNC = ['drop-unit', 'add-unit', 'set-deps', 'move-link', 'blocked-outside', 'cycle']
   for (const a of sync?.actions ?? []) actions.push({ action: a.action, unit: a.unit, detail: a.detail })
-  const order = [...SYNC, 'worker-kind', 'decide', 'split', 'unblock', 'check-worker', 'restack', 'carry', 'review-verdict', 'start-fix', 'start-review', 'deliver', 'open-pr', 'resume', 'fill-slot']
+  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']
   actions.sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action))
   // One restack per unit per pass: the first reason found; the next pass sees the new HEAD.
   const restacked = new Set()
@@ -625,7 +647,18 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   const waiting = []
   for (const a of actions) {
     if (!NEEDS_SLOT.has(a.action)) { due.push(a); continue }
-    if (free > 0) { due.push(unlimited ? { ...a, detail: `${a.detail} [needs a free worker slot]` } : a); free-- } else waiting.push(a)
+    if (free > 0) {
+      const u = byId.get(a.unit)
+      const reviewReady = a.action !== 'start-review' || u.lifecycle?.resources?.some((r) => r.role === 'review' && r.state === 'ready')
+      const needsPreparation = managed(u) && (u.lifecycle?.workspace?.state !== 'ready' || !reviewReady)
+      const removalPending = managed(u) && u.lifecycle?.cleanup?.state === 'applying'
+      const admitted = removalPending ? { action: 'recover-workspace', unit: a.unit,
+        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` }
+        : needsPreparation ? { action: 'prepare-workspace', unit: a.unit,
+        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
+      due.push(unlimited ? { ...admitted, detail: `${admitted.detail} [needs a free worker slot]` } : admitted)
+      free--
+    } else waiting.push(a)
   }
   if (native) oneChange(due)
   const treeChanged = (sync?.actions ?? []).length > 0
@@ -645,7 +678,8 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   const parked = units.filter(notStarted).map((u) => `${u.id} (waits on ${waitsOn(u)})`)
   const built = units.filter((u) => builtWaiting(u) && !u.pr).map((u) => `${u.id} (waits on ${waitsOn(u)})`)
   const openWaiting = units.filter((u) => builtWaiting(u) && u.pr).map((u) => `${u.id} (${u.pr}, waits on ${waitsOn(u)})`)
-  if (!ready.length && units.every((u) => (TERMINAL.has(u.status) || notStarted(u) || builtWaiting(u)) && settledBlock(u) && !sizeHeld(u) && !deciding(u)) && !treeChanged) {
+  const cleanupPending = due.some((a) => a.action === 'cleanup-workspace')
+  if (!ready.length && !cleanupPending && units.every((u) => !hasWorker(u) && (TERMINAL.has(u.status) || notStarted(u) || builtWaiting(u)) && settledBlock(u) && !sizeHeld(u) && !deciding(u)) && !treeChanged) {
     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` })
     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' })
     else if (retryable.some((u) => !u.blockedAt || !Number.isFinite(now))) {
@@ -653,7 +687,10 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
     } else if (retryable.length) {
       const next = retryable.reduce((a, u) => (dueAt(u) < dueAt(a) ? u : a))
       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` })
-    } 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(', ')}` : ''}` })
+    } else {
+      const retained = units.filter((u) => managed(u) && u.lifecycle?.cleanup?.state === 'retained').map((u) => `${u.id}: ${u.lifecycle.cleanup.reason}`)
+      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('; ')}` : ''}` })
+    }
   }
   // How long each due action has gone undone, from when it was first printed.
   const nextSeen = {}
@@ -823,7 +860,7 @@ if (isMainModule(import.meta.url)) {
     if (opts.json) process.stdout.write(`${JSON.stringify({ ...result, mode, exitDue }, null, 2)}\n`)
     else if (mode !== 'full') {
       const view = narrowView(plan, result)
-      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))]
+      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))]
       process.stdout.write(`${mode === 'off' ? `${view.split('\n')[0].replace(/: .*$/, '')}${guardNames.length ? ` (clear first: ${guardNames.join(', ')})` : ''}` : view}\n`)
       process.stdout.write(`${budgetLine(result.capacity)}\n`)
       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)) {
 // The narrow view: whether the run is done, which units have work, the guards, and what waits on
 // the human. It leaves each unit's next step to the coordinator.
 export function narrowView(plan, result) {
-  const GUARDS = new Set(['decide', 'review-verdict', 'unblock', 'worker-kind', 'split', 'sync', 'add-unit', 'drop-unit', 'set-deps', 'move-link', 'blocked-outside'])
+  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'])
   const units = new Map((plan.units ?? []).map((u) => [String(u.id), u]))
   const guards = result.due.filter((a) => GUARDS.has(a.action)).map((a) => `${a.unit ?? 'run'}: ${a.detail}`)
   const work = [...new Set([...result.due, ...result.waiting].filter((a) => a.unit && !GUARDS.has(a.action) && a.action !== 'wait').map((a) => a.unit))]

package/skills/engineering/resolve-issues/scripts/rehydrate.mjs

@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url'
 
 import { workerResources } from '../../engineering-runtime/scripts/installation-resolver.mjs'
 import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
-import { RULES, SKILL_PATH } from './next-actions.mjs'
+import { RULES, RUN_SKILLS, SKILL_PATH, workspaceCleanupSettled } from './next-actions.mjs'
 
 export const ACTIVE_HOURS = 24
 const SCRIPTS = dirname(fileURLToPath(import.meta.url))
@@ -52,6 +52,7 @@ export function activeRuns(cwd, now = Date.now(), hours = ACTIVE_HOURS) {
     if (now - mtime > hours * 3_600_000) continue
     let plan
     try { plan = JSON.parse(readFileSync(file, 'utf8')) } catch { continue }
+    if (plan.skill !== undefined && !RUN_SKILLS.includes(plan.skill)) continue
     const units = (Array.isArray(plan?.units) ? plan.units : plan?.issues) ?? []
     const open = units.filter((u) => !DONE.has(u?.status)).length
     if (!open) continue
@@ -61,6 +62,39 @@ export function activeRuns(cwd, now = Date.now(), hours = ACTIVE_HOURS) {
   return runs.sort((a, b) => b.mtime - a.mtime).map(({ mtime, ...r }) => r)
 }
 
+// Recovery discovery must not activate a workflow, and has no age cutoff.
+export function cleanupRuns(cwd) {
+  const root = runsRoot(cwd)
+  if (!root) return []
+  let names
+  try { names = readdirSync(root) } catch { return [] }
+  const out = []
+  for (const name of names) {
+    const dir = join(root, name)
+    let plan
+    try { plan = JSON.parse(readFileSync(join(dir, 'task-plan.json'), 'utf8')) } catch { continue }
+    if (Array.isArray(plan.units) && Array.isArray(plan.issues) && JSON.stringify(plan.units) !== JSON.stringify(plan.issues)) {
+      out.push({ dir, units: [], reason: 'conflicting units and issues rosters; ownership requires reconciliation' })
+      continue
+    }
+    const units = Array.isArray(plan.units) ? plan.units : plan.issues
+    if (!Array.isArray(units)) continue
+    const pending = units.filter((u) => u.status === 'succeeded' && u.delivery === 'merged' && u.workspace && !workspaceCleanupSettled(u))
+    if (pending.length) out.push({ dir, units: pending.map((u) => String(u.id)),
+      ...(pending.some((u) => plan.workspaceLifecycle !== 1 && u.lifecycle?.version !== 1) ? { reason: 'legacy workspace ownership is unresolved; inventory only, never automatic adoption or deletion' } : {}) })
+  }
+  return out.sort((a, b) => a.dir.localeCompare(b.dir))
+}
+
+export function cleanupMessage(runs) {
+  if (!runs.length) return ''
+  return [
+    'Read-only recovery notice: these delivered units still have pending or interrupted workspace cleanup:',
+    ...runs.map((r) => `- ${r.dir}: ${r.units.join(', ') || 'ownership unresolved'}${r.reason ? ` (${r.reason})` : ''}`),
+    '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.',
+  ].join('\n')
+}
+
 export function message(runs, { skillPath = SKILL_PATH, rushSkillPath = RUSH_SKILL_PATH } = {}) {
   if (!runs.length) return ''
   if (runs.some((run) => run.installation)) {
@@ -103,7 +137,7 @@ export function main(argv) {
     if (hook) {
       try { cwd = JSON.parse(readFileSync(0, 'utf8'))?.cwd || cwd } catch { /* no input: keep cwd */ }
     }
-    const text = message(activeRuns(cwd))
+    const text = [message(activeRuns(cwd)), cleanupMessage(cleanupRuns(cwd))].filter(Boolean).join('\n\n')
     if (text) process.stdout.write(hook ? `${hookOutput(text)}\n` : `${text}\n`)
   } catch (error) {
     process.stderr.write(`rehydrate: ${error.message}\n`)

package/skills/engineering/resolve-issues/scripts/review-verdict.mjs

@@ -32,15 +32,16 @@
 //      the fix worker's whole finding list. `action` says how to fix, from a
 //      comparison with the previous round's file (`<unit>-r<N-1>.json` beside
 //      it, or --prior):
-//        fix         first blocking round: fix each finding's rule at its one
-//                    owner and close every row in its paths
+//        fix         first blocking round: fix each finding's rule across its
+//                    applicable paths and close every row
 //        test-first  a P0/P1 came back after a fix: name the rule it breaks,
-//                    list every path that can break it, test each path, see
-//                    the tests fail, then fix until all pass, with the
+//                    list the applicable paths, reuse sufficient tests and add
+//                    focused cases for missing proof, see the open cases fail,
+//                    then fix until all pass, with the
 //                    escalation model
 //        one-by-one  only new P0/P1, introduced by the last fix: one finding
 //                    per fix worker, in turn, the smallest change that closes
-//                    every row at the rule's owner
+//                    every row across the applicable paths
 //   5  wait: no P0/P1 is open, but a GitHub reviewer whose changes request a fix brief
 //      already carried has not re-reviewed (`awaiting`, from github-reviews.mjs merge);
 //      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 = {}) {
 }
 
 const INSTRUCTIONS = {
-  '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`.',
-  '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.',
-  '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.',
+  '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.',
+  '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.',
+  '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.',
 }
 
 // The fix worker's brief carries only P0/P1 findings; P2/P3 never reach it.

package/skills/engineering/resolve-issues/scripts/workspace-lifecycle.mjs

@@ -0,0 +1 @@
+export * from '../../harness-runtime/workspace-lifecycle.mjs'

package/skills/engineering/resolve-release/SKILL.md

@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
 disable-model-invocation: true
 metadata:
   workflow-role: coordinator
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Resolve release

package/skills/engineering/rush-issues/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-issues
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush issues (shortcut of resolve-issues)
@@ -55,7 +55,9 @@ question.
    mode too: keep one immediate checkpoint per active unit, justify infrastructure and
    reassess repeated non-convergence. More worker activity is not a reason to reset it.
    The shared [task-plan checkpoints](../resolve-issues/references/task-plan.md#checkpoints)
-   apply too: on Pi, bind or reload through `update_plan` with the absolute
-   workflow path and persisted revision (no event means read-only), then
-   save transitions through its `workflow` payload. The TUI refreshes
-   automatically; never edit the bound plan directly.
+   apply too: when `update_todo` is advertised, capture the known outcome before
+   substantive work, then bind or reload with the absolute workflow path and
+   persisted revision. No event means the plan is read-only; save transitions
+   through its `workflow` payload. Never edit a bound plan directly. When the
+   optional tool is absent or disabled, use the workflow's file transition; never
+   enable the interface as a precondition.

package/skills/engineering/rush-release/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   workflow-role: coordinator
 dependencies:
   - resolve-release
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Rush release (shortcut of resolve-release)

package/skills/engineering/test-quality/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: test-quality
 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)."
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Test Quality
 
 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).
 
-- **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.
+- **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.
 - **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.
 - **Persist mode**: only when the user asks, write the principles into the repo's `CONTRIBUTING.md` ([persist](#persist-mode)).
 
@@ -22,6 +22,21 @@ A test is worth keeping when it fails for a real bug and stays green through a h
 | 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 |
 | 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` |
 
+## Scope while writing
+
+Use these principles to judge the tests the task needs, not to start a suite-wide
+cleanup. First identify the requested behavior or concrete regression and reuse
+existing tests that prove it. Add focused assertions at the lowest level that
+observes the real outcome; do not automatically duplicate them across test layers.
+
+Before testing a defensive branch, check that its behavior belongs to the supported
+contract. A new guard or fallback does not create its own testing requirement.
+Speculative failures, coverage percentages, and test counts do not justify expanding
+a feature into a harness, framework, or gate project. Keep binding checks and material
+security, money, tenancy, and data-integrity proof; report unrelated debt rather than
+fixing it. Stop once the agreed behavior is sufficiently proven. Broad audits and
+convention persistence remain separate, explicitly requested tasks.
+
 ## The one question
 
 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
 
 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.
 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.
-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.
+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.
 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.
 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.
 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
 
 ## The lint
 
-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).
+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).
 
 ## Common wrong answers
 

package/skills/engineering/test-quality/references/lint.md

@@ -4,7 +4,7 @@
 
 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.
 
-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.
+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.
 
 | rule | principle | severity | finds |
 |---|---|---|---|

package/skills/engineering/test-quality/references/principles.md

@@ -49,14 +49,14 @@
 
 ## 3. Fake only what you don't own
 
-**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.
+**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.
 
 **Done right.**
 - Real Postgres with migrations; only the payment provider faked.
 - 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".
 
 **Common failures.**
-- *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.
+- *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.
 - *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.
 - *Mocked transaction:* "updates atomically" with `$transaction: (fn) => fn()`.
 - *Layout in jsdom:* `toHaveClass('min-h-11')` to prove a 44px target. jsdom has no layout.

package/skills/engineering/test-quality/references/testing-conventions.md

@@ -2,7 +2,7 @@
 
 1. Run the code and assert what it does; never match the text of docs, prompts, source files, or migrations.
 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.
-3. Fake only third-party services, the clock, and randomness; run your own database and services for real.
+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.
 4. Make every assertion able to fail, and assert everything the test name promises.
 5. Test each behavior once, at the lowest level that proves it; delete tests of dead code.
 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.

package/skills/risk-compliance/compliance-audit/SKILL.md

@@ -2,7 +2,7 @@
 name: compliance-audit
 version: 2.9.0
 description: "Audit operations against financial-compliance checklists (AML/KYC, VARS, PCI-DSS, TPA oversight, onboarding, transaction monitoring). Produces tracker.md (with a tracker.xlsx export) and phase-trail.md with layered validation; cites evidence by original filename. Input: reg-parser or the built-in VARS checklist."
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Compliance Audit
@@ -12,13 +12,9 @@ keyed by control item that the client can update through remediation —
 alongside a phase trail companion file (work product) that preserves what each
 phase saw before the tracker was finalised.
 
-## Audience
-
-The user is a **compliance auditor or analyst** working in regulated financial
-services — payments, banking, fintech, insurance. They audit against financial
-regulatory frameworks: AML regulations, KYC requirements, financial reporting
-standards, local financial authority rules, and card-scheme standards such as
-VARS.
+Read [audience and report handoff](references/audience-and-reports.md) before starting;
+it defines the auditor audience and the optional report-writing handoff without replacing
+this assessment or its validation.
 
 ## Audit Workflow
 

package/skills/risk-compliance/compliance-audit/references/audience-and-reports.md

@@ -0,0 +1,12 @@
+# Audience and report handoff
+
+The user is a **compliance auditor or analyst** working in regulated financial
+services -- payments, banking, fintech, insurance. They audit against financial
+regulatory frameworks: AML regulations, KYC requirements, financial reporting
+standards, local financial authority rules, and card-scheme standards such as
+VARS.
+
+When the user also requests an analytical report, hand the validated tracker and phase trail
+to `write-report` when installed. Its compliance branch owns audit, external, management and
+VARS report writing; it does not replace this assessment or its validation. Without that skill,
+deliver the audit artifacts and state that the report-writing stage remains outstanding.

package/skills/risk-compliance/contract-compare/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-compare
 description: "Compare two or more contracts side-by-side for structured diff, gap analysis, and benchmarking. Use when: comparing contracts or agreements, contract diff, compare terms, vendor-vs-vendor, compare our template vs theirs, compliance gap between contracts. NOT for single-contract risk review — use contract-review for that."
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Compare
@@ -97,6 +97,22 @@ Wait for all dimension subagents to return.
 
 ## Step 4: Build Comparison Report
 
+Required report-stage resource: the installed `house-style` skill. This skill remains available
+as an ungrouped native selection; native Skills CLI does not install dependencies automatically.
+Select `house-style` with `contract-compare`, or install the Core and Risk & Compliance npm packages.
+Resolve its installed base directory, not a repository-only `skills/writing/` path.
+
+Before drafting or substantively reviewing an analytical report, read
+`{house-style baseDir}/references/analytical-reporting.md`,
+`{house-style baseDir}/references/analytical-writing-patterns.md`, and
+`{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
+loading and delegation instructions; report a missing or unreadable reference as a
+blocker rather than claiming the report stage is complete. Apply them within the
+requested scope, including a chat-only response; do not create a report for an
+audit-only or narrower request. Preserve the selected dimensions, clause evidence,
+assessments, legal caveats, optional mandate tracing, and the required report format.
+Generic editorial checks do not replace specialist legal review.
+
 **House style.** Use the nearest `WRITING.md`: start in the first contract's folder (pasted text: the output
 folder, else the working directory), then parents up to the repository root; never the home
 directory or above. Rate every issue from the evidence first; the style changes

package/skills/risk-compliance/contract-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: contract-review
 description: "Review contracts for legal, commercial, and compliance risks via convert → chunk review → merge → validate (+ optional mandate preprocessing). Use for reviewing, auditing, or checking any contract, agreement, NDA, MSA, or SLA; input a file path (PDF/DOCX/TXT) or pasted text."
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Contract Review
@@ -106,6 +106,10 @@ Start all chunk subagents in parallel and wait for all to complete.
 
 ## Step 3: Merge Results
 
+Before drafting or substantively reviewing the report, read and follow
+[the analytical report-stage instructions](references/report-stage.md), including all three
+required `house-style` references and their loading/delegation rules. Preserve Step 4 validation.
+
 **House style.** Use the nearest `WRITING.md`: start in the contract file's folder (pasted text: the output
 folder, else the working directory), then parents up to the repository root; never the home
 directory or above. Rate every issue from the evidence first: the style changes wording, never a rating,
@@ -182,6 +186,7 @@ Substitute `{contract-review baseDir}` and `{reg-parser baseDir}` as in Step 2:
 You are validating a contract review report for completeness and consistency.
 
 Load the review criteria from: {contract-review baseDir}/references/review-criteria.md
+Load the analytical reporting instructions from: {house-style baseDir}/references/analytical-reporting.md, {house-style baseDir}/references/analytical-writing-patterns.md, and {house-style baseDir}/references/definitions-and-metrics.md
 Load any preprocessed mandate files from: {reg-parser baseDir}/references/mandates/ (read all .md files present)
 Use mandate files to verify P10 annotations ([Mandated]/[Permitted]/[Counterparty-Added]) are accurate.
 

package/skills/risk-compliance/contract-review/references/report-stage.md

@@ -0,0 +1,17 @@
+# Analytical report stage
+
+Required report-stage resource: the installed `house-style` skill. This skill remains available
+as an ungrouped native selection; native Skills CLI does not install dependencies automatically.
+Select `house-style` with `contract-review`, or install the Core and Risk & Compliance npm packages.
+Resolve its installed base directory, not a repository-only `skills/writing/` path.
+
+Before drafting or substantively reviewing an analytical report, read
+`{house-style baseDir}/references/analytical-reporting.md`,
+`{house-style baseDir}/references/analytical-writing-patterns.md`, and
+`{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
+loading and delegation instructions; report a missing or unreadable reference as a
+blocker rather than claiming the report stage is complete. Apply them within the
+requested scope, including a chat-only response; do not create a report for an
+audit-only or narrower request. Preserve this skill's review criteria, evidence,
+severity ratings, mandated layout, and Step 4 specialist validation. Generic editorial
+checks do not replace legal validation.

package/skills/risk-compliance/doc-authenticity/SKILL.md

@@ -3,7 +3,7 @@ name: doc-authenticity
 version: 0.4.1
 description: "Screen PDF documents and raster images for fabrication, tampering, Photoshop or other image-editor use, and content validity. Detects file type, runs format-specific authenticity forensics, classifies bank statements, conversation logs, invoices, agreements, and other documents, then applies type-specific validity checks. Produces separate authenticity (NO_EVIDENCE_OF_MODIFICATION / SUSPICIOUS / LIKELY_MODIFIED / INCONCLUSIVE) and validity (VALID / INVALID / INCONCLUSIVE) verdicts. Use whenever a user asks whether a document, screenshot, scan, statement, invoice, contract, chat log, receipt, or payment evidence is genuine, original, edited, Photoshopped, manipulated, fake, or valid."
 disable-model-invocation: true
-release-version: 0.44.1
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Document and Image Authenticity
@@ -117,6 +117,16 @@ future specialized profile is added.
 
 ### 5. Verdict and report
 
+Before drafting or substantively reviewing an analytical report, read
+`{house-style baseDir}/references/analytical-reporting.md`,
+`{house-style baseDir}/references/analytical-writing-patterns.md`, and
+`{house-style baseDir}/references/definitions-and-metrics.md` directly. Follow their
+loading and delegation instructions; report a missing or unreadable reference as a
+blocker rather than claiming the report stage is complete. Apply them within the
+requested scope, including a chat-only response; do not create a report for an
+audit-only or narrower request. Preserve forensic and validity methods, evidence,
+independent verdicts, required checks, report layout, schema, and validation.
+
 Read `references/verdict-and-report.md`. Apply its rubrics independently to:
 
 - authenticity: `NO_EVIDENCE_OF_MODIFICATION | SUSPICIOUS | LIKELY_MODIFIED | INCONCLUSIVE`

package/skills/risk-compliance/fraud-detection/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO