@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/workflows/independent-review.workflow.js

@@ -0,0 +1,290 @@
+export const meta = {
+  name: 'resolve-issues-independent-review',
+  description: "Fan step 2 (independent review) out across an epic's units — one adversarial reviewer per unit's PR, each on the review model (≠ implementation model), emitting schema'd findings + a calibrated verdict + the previous-findings reconciliation on re-reviews. Read-only: writes no code, posts nothing, asks the human nothing.",
+  phases: [
+    { title: 'Review', detail: 'one review-pr reviewer per unit, on the review model' },
+  ],
+}
+
+// This is the review step of resolve-issues, fanned out across the units that
+// need a (re-)review this round. It preserves both independence guarantees:
+//   - Fresh context: each reviewer is a new subagent.
+//   - Model diversity: each runs on `reviewModel` via opts.model, which MUST
+//     differ from the model that wrote that unit's diff (u.implementationModel
+//     when set — e.g. a spawn-time substitute — else the run-level implementationModel).
+// It is launched by the main-loop orchestrator, so the reviewers sit at the one
+// nesting level the harness allows (they are leaves — they never sub-spawn, so
+// there is no depth-2 cap to degrade them to a same-model self-review). The fix
+// step that consumes these verdicts stays in the main loop (it writes code).
+// The reviewer computes its own diff facts with review-pr's pr-context.mjs —
+// diff-discipline as code, no caller-supplied SHA plumbing.
+//
+// args: {
+//   units: [{
+//     id: string, prRef: string, baseRef: string, contractPath?: string,
+//     highRisk?: boolean,           // unit touches auth/money/tenancy/migration → the
+//                                   // reviewer also runs references/high-risk.md's additions
+//     implementationModel?: string, // the model that wrote THIS unit's diff, when it differs from the
+//                                   // run-level implementationModel (e.g. a substitute re-confirmed on
+//                                   // a spawn-time miss) — the diversity guard compares per unit
+//     lastReviewedSha?: string,     // re-reviews only: the HEAD the prior verdict was rendered
+//                                   // against — scopes the fresh four-axis scan to the
+//                                   // <sha>...HEAD delta (review-pr § Re-review). OMIT to force
+//                                   // a full-scope re-review (high-risk, round 3+, delta outside
+//                                   // the original files, or a rebase — the CALLER decides).
+//     priorFindings?: [{ title: string, axis: string, file: string, line_start: number,
+//       line_count: number, confidence: number, why: string, consequence: string,
+//       recommendation: string, theme: object, hazard_candidate?: object }]
+//       // present on re-reviews; carry each prior finding's hazard_candidate
+//       // VERBATIM so the two-locator rule remains enforceable.
+//   }]
+//   reviewModel: string           // the review model (confirmed upstream)
+//   reviewEffort?: string         // the effort of the banked OPERATING POINT the human
+//                                  // picked for this slot (models.reviewEffort), default high.
+//                                  // Never asked per run: points are confirmed once, when
+//                                  // the model is classified (model-catalog.md `tiers`).
+//   implementationModel: string   // run-level default implementer; the diversity guard compares
+//                                  // per unit, with u.implementationModel overriding this
+//   reviewSkillPath: string       // ABSOLUTE path to review-pr SKILL.md (resolved at pre-flight)
+// }
+const {
+  units = [],
+  reviewModel,
+  reviewEffort = 'high',
+  implementationModel,
+  reviewSkillPath,
+} = args || {}
+
+if (!units.length) {
+  throw new Error('resolve-issues-independent-review: args.units is empty — nothing to review.')
+}
+if (!reviewModel) {
+  throw new Error('resolve-issues-independent-review: args.reviewModel is required — the review must run on a named model so the handoff can prove it differs from the implementer.')
+}
+if (!reviewSkillPath || !reviewSkillPath.startsWith('/')) {
+  // A relative default like 'skills/engineering/review-pr/SKILL.md' only resolves inside the
+  // skills repo itself; in a consumer repo the reviewer's read fails silently and it improvises
+  // a lookalike review from memory. Force the orchestrator to pass the resolved absolute path.
+  throw new Error('resolve-issues-independent-review: args.reviewSkillPath must be the ABSOLUTE path to review-pr/SKILL.md (e.g. ~/.claude/skills/review-pr/SKILL.md resolved) — a relative path breaks outside the skills repo and degrades the review to a memory-reconstructed lookalike.')
+}
+const boundaryKinds = ['head', 'ci', 'contract', 'integration']
+const unitFieldFailures = units.flatMap((u, i) =>
+  ['id', 'prRef', 'baseRef', 'authorizationBoundary'].filter((f) => f === 'authorizationBoundary'
+    ? !(u?.[f] && typeof u[f] === 'object' && boundaryKinds.includes(u[f].kind) && typeof u[f].value === 'string' && u[f].value.trim())
+    : typeof u?.[f] !== 'string' || !u[f].trim()).map((f) => `units[${i}]: ${f} is required`))
+if (unitFieldFailures.length) {
+  throw new Error(`resolve-issues-independent-review: ${unitFieldFailures.join('; ')}`)
+}
+
+// The diversity guard (resolve-issues "Pre-flight"): a same-model review is NOT
+// independent. We do not silently pass it off as one.
+// Per-unit: a unit's diff may have been written by a spawn-time substitute,
+// not the run-level implementationModel — the guard must compare against the model
+// that actually wrote THAT unit's diff (u.implementationModel overrides).
+const unitImplModel = (u) => u.implementationModel || implementationModel
+const notIndependent = units.some((u) => reviewModel === unitImplModel(u))
+if (notIndependent) {
+  log(`WARNING: reviewModel (${reviewModel}) equals the implementation model for at least one unit. Those reviews are NOT INDEPENDENT — same model. Each result is tagged so the handoff reports it as a gap, not a real review.`)
+}
+
+const REVIEW = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['unitId', 'verdict', 'headSha', 'reviewSubject', 'authorizationBoundary', 'findings', 'overMockFindings', 'previousFindingsResolution', 'reviewModel', 'independent', 'contractValidates'],
+  properties: {
+    unitId: { type: 'string' },
+    headSha: { type: 'string', pattern: '^[0-9a-f]{7,64}$', description: 'Exact reviewed HEAD from pr-context.mjs.' },
+    reviewSubject: { type: 'string', enum: ['code', 'evidence'], description: 'Independent round subject; evidence only for a constrained evidence review.' },
+    evidenceClasses: {
+      type: 'array', minItems: 1, uniqueItems: true,
+      items: { type: 'string', enum: ['stale-locator', 'unrun-gate-row', 'stale-stamp', 'contract-drift', 'checklist-row', 'other'] },
+      description: 'Required exactly when reviewSubject is evidence.',
+    },
+    reopenReason: { type: 'string', enum: ['ci-red', 'head-rewritten', 'contract-revised', 'integration-finding', 'external-review'] },
+    authorizationBoundary: {
+      type: 'object', additionalProperties: false, required: ['kind', 'value'],
+      properties: { kind: { type: 'string', enum: ['head', 'ci', 'contract', 'integration'] }, value: { type: 'string', minLength: 1, pattern: '\\S' } },
+    },
+    verdict: {
+      type: 'string',
+      enum: ['PASS', 'NEEDS_CHANGES', 'FAIL', 'BLOCKED'],
+      description: 'review-pr verdict against the current HEAD. PASS = merge-ready (or merge-ready with only non-blocking notes).',
+    },
+    findings: {
+      type: 'array',
+      // GENERATED FROM review-pr/scripts/finding-contract.mjs. The workflow
+      // harness is intentionally import-free, so parity is checked by tests.
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['title', 'axis', 'file', 'line_start', 'confidence', 'why', 'priority'],
+        properties: {
+          title: { type: 'string', minLength: 1, pattern: '\\S', maxLength: 120 },
+          axis: { type: 'string', enum: ['spec', 'coverage', 'correctness', 'standards'] },
+          subject: { type: 'string', enum: ['code', 'evidence'], default: 'code' },
+          in_scope: { type: 'boolean', default: true },
+          priority: { type: 'integer', minimum: 0, maximum: 3 },
+          file: { type: 'string', minLength: 1, pattern: '\\S' },
+          line_start: { type: 'integer', minimum: 1 },
+          line_count: { type: 'integer', minimum: 1 },
+          confidence: { type: 'number', minimum: 0, maximum: 1 },
+          why: { type: 'string', minLength: 1, pattern: '\\S' },
+          consequence: { type: 'string', minLength: 1, pattern: '\\S' },
+          recommendation: { type: 'string', minLength: 1, pattern: '\\S' },
+          theme: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id', 'kind', 'contract'],
+            properties: {
+              id: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+              kind: { type: 'string', enum: ['other', 'state-machine', 'concurrency'] },
+              contract: { type: 'string', minLength: 1, pattern: '\\S' },
+              stateSpace: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['states', 'taskKinds'],
+                properties: {
+                  states: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', minLength: 1, pattern: '\\S' } },
+                  taskKinds: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', minLength: 1, pattern: '\\S' } },
+                },
+              },
+            },
+            allOf: [{
+              if: { properties: { kind: { enum: ['state-machine', 'concurrency'] } } },
+              then: { required: ['stateSpace'] },
+            }, {
+              if: { properties: { kind: { const: 'other' } } },
+              then: { not: { required: ['stateSpace'] } },
+            }],
+          },
+          hazard_candidate: {
+            type: 'object',
+            additionalProperties: false,
+            anyOf: [
+              { required: ['section', 'id', 'rule', 'prove'] },
+              { required: ['covered_by'] },
+            ],
+            properties: {
+              section: { type: 'string', enum: ['auth', 'money', 'tenancy', 'migration', 'cross-cutting'] },
+              id: { type: 'string', pattern: '^[a-z][a-z0-9-]*$' },
+              rule: { type: 'string', minLength: 1, pattern: '\\S' },
+              prove: { type: 'string', minLength: 1, pattern: '\\S' },
+              covered_by: { type: 'string', minLength: 1, pattern: '\\S' },
+            },
+          },
+        },
+      },
+    },
+    overMockFindings: {
+      type: 'array',
+      description: "Verbatim `findings` channel of review-pr's `scripts/scan-diff.mjs` over the base...HEAD diff — the decidable over-mock screen. Every entry is a zero-tolerance blocker (a vi/jest/vitest.mock of a first-party internal seam), no waiver. An empty array is valid ONLY when it is the script's actual output, never a stand-in for 'I checked the mocks'. A review that omits this field did not run the screen and does not satisfy the step.",
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['file', 'line', 'target'],
+        properties: {
+          file: { type: 'string' },
+          line: { type: 'integer' },
+          target: { type: 'string', description: 'the mocked first-party seam, e.g. @/lib/intake/case-store' },
+        },
+      },
+    },
+    previousFindingsResolution: {
+      type: 'array',
+      description: 'Re-reviews only: one row per prior finding, reconciled against the CURRENT tree. A finding the PR claims fixed but with no verifiable locator stays Unresolved.',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['finding', 'themeId', 'status', 'evidence'],
+        properties: {
+          finding: { type: 'string' },
+          themeId: { type: 'string' },
+          status: { type: 'string', enum: ['Resolved', 'Unresolved', 'Partially resolved'] },
+          evidence: { type: 'string', description: 'file:line proving the resolution, or why it is still open' },
+        },
+      },
+    },
+    reviewModel: { type: 'string', pattern: '\\S' },
+    independent: { type: 'boolean', description: 'false when reviewModel === implementationModel' },
+    contractValidates: { type: 'boolean', description: 'result of running coverage-checklist.mjs validate on the Review Contract' },
+    round1Depth: {
+      // HIGH-RISK UNITS ONLY (references/high-risk.md): live-endpoint probing +
+      // shared-consumer impact, recorded with evidence. Lean-lane reviews omit it.
+      type: 'object',
+      additionalProperties: false,
+      required: ['liveEndpointProbing', 'sharedConsumerImpact'],
+      properties: {
+        liveEndpointProbing: {
+          type: 'object', additionalProperties: false, required: ['status', 'evidence'],
+          properties: { status: { type: 'string', enum: ['completed', 'not-applicable'] }, evidence: { type: 'string', minLength: 1, pattern: '\\S' } },
+        },
+        sharedConsumerImpact: {
+          type: 'object', additionalProperties: false, required: ['status', 'evidence'],
+          properties: { status: { type: 'string', enum: ['completed', 'not-applicable'] }, evidence: { type: 'string', minLength: 1, pattern: '\\S' } },
+        },
+      },
+    },
+  },
+  allOf: [{
+    if: { properties: { reviewSubject: { const: 'evidence' } }, required: ['reviewSubject'] },
+    then: { required: ['evidenceClasses'] },
+    else: { not: { required: ['evidenceClasses'] } },
+  }],
+}
+
+phase('Review')
+log(`Reviewing ${units.length} unit(s) on ${reviewModel}${notIndependent ? ' (some units NOT INDEPENDENT — same model)' : ` (impl: ${implementationModel || 'unknown'})`}`)
+
+const results = (await parallel(
+  units.map((u) => () => {
+    // Re-review is signaled by EITHER prior findings to reconcile OR a recorded
+    // lastReviewedSha (a round-2+ unit can carry the SHA with no prior findings —
+    // a CI-only fix, or a clean round followed by a new commit — and still owes
+    // the delta-scope contract, not a "first review").
+    const priorFindings = Array.isArray(u.priorFindings) ? u.priorFindings : []
+    const isRereview = Boolean(u.lastReviewedSha) || priorFindings.length > 0
+    const unitNotIndependent = reviewModel === unitImplModel(u)
+    return agent(
+      `Apply the review-pr skill (read ${reviewSkillPath}) adversarially to ONE pull request, READ-ONLY (do not push, comment, or change anything):\n\n` +
+      `  unit:     ${u.id}\n` +
+      `  PR:       ${u.prRef}\n` +
+      `  base:     ${u.baseRef}\n` +
+      `  contract: ${u.contractPath || '(none — note its absence as a finding)'}\n\n` +
+      `Scope to the net ${u.baseRef}...HEAD diff (compute the merge-base and range with review-pr's scripts/pr-context.mjs — diff-discipline as code, no hand-typed SHAs). Search adversarially across the four axes; return schema'd findings — each with a title, axis, a real file + line_start, a numeric confidence, a priority (integer 0-3, the ONE severity scale — required), and why it breaks (consequence/recommendation/line_count welcome but optional). Set in_scope to false only when the finding is NOT about this diff (pre-existing / out-of-scope code); it defaults true. Do NOT emit a 'blocking' field or any [P1]/F-/N- label prefix in the title — the label (BLOCK-n/NOTE-n) and the verdict are RENDERED mechanically from {priority, in_scope} by post-review.mjs; a finding blocks the PR only when in_scope && priority<=1. Set subject to 'evidence' when the fix would touch no source file (contract wording, checklist rows, evidence locators, @level tags) and 'code' otherwise; omitting it means 'code'. The caller routes an unmoved-diff round on this, so misclassifying a code defect as evidence skips its adversarial re-review — when unsure, leave it 'code'. A state-machine/concurrency finding also carries a durable stable theme (kebab-case theme.id, kind, the general violated contract, and declare the full stateSpace) — a recurrence keeps its theme.id; do not mint a new id for an adjacent counterexample; other findings may omit theme. ` +
+      `Run \`coverage-checklist.mjs validate\` on the Review Contract and set contractValidates. ` +
+      `Run review-pr's mechanized over-mock screen (\`scripts/scan-diff.mjs\` over the ${u.baseRef}...HEAD diff) and set overMockFindings to its decidable \`findings\` channel VERBATIM — empty array only if that is the script's actual output, never a stand-in for "I checked the mocks". Every entry is a zero-tolerance blocker (no waiver). ` +
+      `Specifically hunt for over-mock (a vi/jest/vitest.mock of a first-party internal seam — store/engine/action/DB — or first-party page.route/route.fulfill/MSW interception in a journey), skip-to-green, weakened assertions, fixed-timeouts, and assertions made against 404/empty/error pages — these fail the review regardless of CI color. Do NOT reason inside the mocked boundary: a well-asserted unit test that stubs an internal seam is Over-mocked, not covered. ` +
+      `Return a calibrated verdict (PASS only when merge-ready against the CURRENT HEAD): a blocker must map to a named review-pr blocking class; anything else is a note inside a PASS.\n\n` +
+      (u.highRisk
+        // The additions are inlined right here, so the reference is provenance,
+        // not something the spawn must resolve — but it is still a repo-relative
+        // skills path in a spawn prompt, which is the shape the absolute-path rule
+        // exists to keep out of prompts entirely. Named descriptively instead, the
+        // way high-risk.md's own reviewer section does.
+        ? `This unit is HIGH-RISK (auth/money/tenancy/migration) — apply resolve-issues' high-risk reviewer additions: read the repo hazards file (docs/domain-hazards.md, via the "Domain hazards" index in AGENTS.md/CLAUDE.md) plus review-pr's domain-hazards catalog and adversarially hunt the diff against every item — any hit is a blocking code-correctness finding with a hazard_candidate (the ready-to-paste row, or covered_by; you are read-only). Also complete round-1 depth: probe each changed live endpoint against the real running surface and trace the changed contract through every shared first-party consumer; record round1Depth with completed + concrete evidence, or not-applicable + a specific reason — never a silent deferral.\n\n`
+        : `This unit is lean-lane: no hazard hunt, no round1Depth — omit that field.\n\n`) +
+      (isRereview
+        ? `This is a RE-REVIEW. Reconcile EVERY prior finding against the current tree and fill previousFindingsResolution. A finding the PR claims resolved but whose fix has no verifiable locator — or is still present — stays Unresolved; it does not clear on the producer's say-so. A prior finding that carried a hazard_candidate needs BOTH locators to reach Resolved: the code fix AND its docs/domain-hazards.md row (or an explicit covered-by) — code-only is Partially resolved. ` +
+          (u.lastReviewedSha
+            ? `DELTA SCOPE (review-pr § Re-review): run the fresh four-axis scan on the ${u.lastReviewedSha}...HEAD delta only — the commits added since the prior verdict — plus the prior-findings reconciliation; the decidable screens (scan-diff, checklist validate) still run over the full ${u.baseRef}...HEAD diff, and the verdict still covers the whole PR. `
+            : `FULL SCOPE: no lastReviewedSha was provided — re-review the whole ${u.baseRef}...HEAD diff. `) +
+          (priorFindings.length
+            ? `Prior findings:\n${JSON.stringify(priorFindings)}\n\n`
+            : `There are no prior findings to reconcile (the prior round ended clean) — previousFindingsResolution is an empty array; the scope instruction above still applies.\n\n`)
+        : `This is a first review — previousFindingsResolution is an empty array.\n\n`) +
+      `Return headSha as the exact reviewed HEAD from pr-context.mjs. Set reviewSubject to evidence only when this was explicitly constrained to evidence; otherwise code. An evidence subject MUST return one or more evidenceClasses from stale-locator|unrun-gate-row|stale-stamp|contract-drift|checklist-row|other; a code subject MUST omit evidenceClasses. Echo authorizationBoundary=${JSON.stringify(u.authorizationBoundary)} exactly — it is caller authorization, never reviewer inference. ${u.reopenReason ? `Echo reopenReason=${JSON.stringify(u.reopenReason)} exactly; it is caller authorization, never reviewer inference. ` : 'Omit reopenReason; the caller did not authorize a post-PASS reopen. '}` +
+      `Set reviewModel="${reviewModel}" and independent=${!unitNotIndependent}.` +
+      (unitNotIndependent ? ` (independent is false because the review model equals the model that wrote this unit's diff — say so plainly; do not present this as a real independent review.)` : ''),
+      { label: `review:${u.id}`, phase: 'Review', model: reviewModel, effort: reviewEffort, schema: REVIEW }
+    )
+  })
+)).filter(Boolean)
+
+const pass = results.filter((r) => r.verdict === 'PASS').length
+const dependentCount = results.filter((r) => !r.independent).length
+log(`Reviewed ${results.length}/${units.length}: ${pass} PASS, ${results.length - pass} need work${dependentCount ? ` — ${dependentCount} NOT independent (same-model)` : ''}`)
+// `independent` is computed from the UNITS (deterministic — the same units.some()
+// guard as above), never from the agents' self-reported flags: a same-model unit
+// whose reviewer errored out would vanish from `results` and make a self-reported
+// aggregate read independent when the wave was not.
+return { results, reviewModel, implementationModel: implementationModel || null, independent: !notIndependent }

package/skills/engineering/resolve-issues/workflows/prior-art-scan.workflow.js

@@ -0,0 +1,80 @@
+export const meta = {
+  name: 'resolve-issues-prior-art-scan',
+  description: "Fan the prior-art check out across an epic's units — one read-only investigator per unit checking open/merged PRs, the codebase, and issue state, then routing each unit (skip / resume PR / scope-remaining / proceed). Read-only: writes no code, opens no PRs, asks the human nothing.",
+  phases: [
+    { title: 'Scan', detail: 'one prior-art investigator per work unit' },
+  ],
+}
+
+// This is the intake prior-art check of resolve-issues, fanned out across the epic's units. It is
+// READ-ONLY investigation: agents run `gh`/`git` queries only, write no code,
+// open/close no PRs, and never hit a human gate. The scheduler in the main loop
+// consumes the routing verdicts to decide which units enter the delivery loop
+// (and where each enters it). See resolve-issues SKILL.md, "Intake & scheduling".
+//
+// args: {
+//   units: [{ id: string, title: string, slug?: string, acSummary?: string }]
+//   defaultBranch?: string   // e.g. "main" — helps the merged/landed check
+// }
+const { units = [], defaultBranch = 'main' } = args || {}
+
+if (!units.length) {
+  throw new Error(
+    'resolve-issues-prior-art-scan: args.units is empty. The main-loop scheduler must normalize the ' +
+    'epic to work units BEFORE fanning out — the workflow does not enumerate sub-issues itself.'
+  )
+}
+
+const PRIOR_ART = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['unitId', 'finding', 'locators', 'recommendation', 'enterAtStep'],
+  properties: {
+    unitId: { type: 'string' },
+    finding: {
+      type: 'string',
+      enum: ['merged', 'open-pr', 'partial', 'nothing'],
+      description: 'merged/landed in codebase | an open PR exists | partially implemented | nothing found',
+    },
+    locators: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'evidence: PR #, branch name, commit SHA, or file:line where existing work lives',
+    },
+    recommendation: {
+      type: 'string',
+      description: 'skip (already done — recommend closing the issue) | resume PR #N | scope remaining work only | proceed fresh',
+    },
+    enterAtStep: {
+      type: 'string',
+      enum: ['skip', 'review', 'implement-remaining', 'implement'],
+      description: 'where this unit enters the delivery loop: skip | resume an open PR at the review step | implement only the remaining gap | implement fresh',
+    },
+  },
+}
+
+phase('Scan')
+log(`Prior-art scan across ${units.length} unit(s)`)
+
+const results = (await parallel(
+  units.map((u) => () =>
+    agent(
+      `READ-ONLY prior-art check for one work unit (resolve-issues intake). Do NOT write code, open PRs, or change anything — only investigate, using read-only \`gh\`/\`git\` queries.\n\n` +
+      `  unit:    ${u.id} — ${u.title}\n` +
+      `  slug:    ${u.slug || '(none)'}\n` +
+      `  ACs:     ${u.acSummary || '(none provided — search by title/slug)'}\n\n` +
+      `Check all three places and route on what you find:\n` +
+      `  1. Open / merged PRs — \`gh pr list --state all --search "${u.id} OR ${u.slug || u.title}"\` and \`gh pr list --search "in:body Closes #${u.id}"\`; scan branch names referencing the issue.\n` +
+      `  2. The codebase — search for the symbols/routes/endpoints/behavior the ACs describe; \`git log --oneline --grep "#${u.id}"\` against ${defaultBranch}.\n` +
+      `  3. Issue state — already closed, or linked to a merged PR?\n\n` +
+      `Return the finding (merged | open-pr | partial | nothing), the evidence locators (PR #, branch, commit, or file:line), a recommendation, and where the unit should enter the delivery loop. ` +
+      `If you are unsure whether existing work truly satisfies the unit, say so in the recommendation and route to "implement" rather than silently assuming done.`,
+      { label: `prior-art:${u.id}`, phase: 'Scan', schema: PRIOR_ART }
+    )
+  )
+)).filter(Boolean)
+
+const skip = results.filter((r) => r.enterAtStep === 'skip').length
+const resume = results.filter((r) => r.enterAtStep === 'review').length
+log(`Scanned ${results.length}/${units.length}: ${skip} already done, ${resume} resumable open PR(s)`)
+return { results }

package/skills/engineering/resolve-issues/workflows/workflow-smoke.mjs

@@ -0,0 +1,102 @@
+// Shared smoke-test helpers for .workflow.js harness scripts (consumed by
+// resolve-issues' workflows.test.mjs).
+//
+// The scripts only fully run inside the Workflow harness (agent/parallel/etc.
+// are injected globals), so these helpers pin the decidable floor instead:
+//   - the file parses (a syntax error would otherwise surface mid-run);
+//   - `meta` is a PURE literal with name/description/phases (the harness contract);
+//   - every phase('X') call uses a title declared in meta.phases;
+//   - the input guards throw informative errors instead of running agents on
+//     an empty work-list (the main loop must scout inputs first).
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function loadWorkflowSource(file) {
+  return fs.readFileSync(file, 'utf8')
+}
+
+// Extract the `export const meta = {...}` literal by brace-matching and
+// evaluate it standalone — exactly what "pure literal, no computed values"
+// guarantees is possible.
+export function extractMeta(src, file) {
+  const start = src.indexOf('export const meta')
+  assert.notEqual(start, -1, `${file}: missing \`export const meta\``)
+  const braceStart = src.indexOf('{', start)
+  let depth = 0
+  let end = -1
+  for (let i = braceStart; i < src.length; i++) {
+    const ch = src[i]
+    if (ch === '{') depth++
+    else if (ch === '}') { depth--; if (depth === 0) { end = i; break } }
+  }
+  assert.notEqual(end, -1, `${file}: unbalanced braces in meta`)
+  const literal = src.slice(braceStart, end + 1)
+  // A pure literal evaluates with no scope at all; a computed meta throws here.
+  return new Function(`'use strict'; return (${literal})`)()
+}
+
+// Compile + run the script body under stub harness globals. `export ` is
+// stripped (the body otherwise has no module syntax — the harness forbids
+// imports/fs). Returns a promise that settles the way the harness would.
+export function runWorkflow(file, { args, agent } = {}) {
+  const src = loadWorkflowSource(file).replace(/^export\s+const\s+meta/m, 'const meta')
+  const fn = new Function(
+    'args', 'agent', 'parallel', 'pipeline', 'phase', 'log', 'budget', 'workflow',
+    `'use strict'; return (async () => {\n${src}\n})()`
+  )
+  const deny = (name) => async () => { throw new Error(`${name}() must not be reached in this smoke test`) }
+  return fn(
+    args,
+    agent || deny('agent'),
+    async (thunks) => Promise.all(thunks.map((t) => t().catch(() => null))),
+    deny('pipeline'),
+    () => {},
+    () => {},
+    { total: null, spent: () => 0, remaining: () => Infinity },
+    deny('workflow'),
+  )
+}
+
+// Register the standard smoke tests for every .workflow.js in `dir`, plus the
+// per-script input-guard assertions in `guards`:
+//   { '<test name>': { file, args, message } }  → expects runWorkflow to reject.
+export function smokeTestWorkflows(dir, guards) {
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.workflow.js'))
+  assert.ok(files.length > 0, `no .workflow.js files found in ${dir}`)
+
+  for (const f of files) {
+    const file = path.join(dir, f)
+    const src = loadWorkflowSource(file)
+
+    test(`${f}: meta is a pure literal with the required harness fields`, () => {
+      const meta = extractMeta(src, f)
+      assert.equal(typeof meta.name, 'string')
+      assert.ok(meta.name.length > 0)
+      assert.equal(typeof meta.description, 'string')
+      assert.ok(Array.isArray(meta.phases) && meta.phases.length > 0, `${f}: meta.phases missing/empty`)
+      for (const p of meta.phases) assert.equal(typeof p.title, 'string')
+    })
+
+    test(`${f}: every phase() call uses a title declared in meta.phases`, () => {
+      const meta = extractMeta(src, f)
+      const declared = new Set(meta.phases.map((p) => p.title))
+      for (const m of src.matchAll(/\bphase\(\s*(['"`])([^'"`]+)\1\s*\)/g)) {
+        assert.ok(declared.has(m[2]), `${f}: phase('${m[2]}') has no matching meta.phases entry`)
+      }
+    })
+
+    test(`${f}: body compiles and is import-free (harness constraint)`, () => {
+      assert.doesNotMatch(src, /^\s*import\s/m, `${f}: workflow scripts cannot import (no module access in the harness)`)
+      runWorkflow(file, { args: undefined }).catch(() => {}) // compile check; rejections are asserted per-guard
+    })
+  }
+
+  for (const [name, { file, args, message }] of Object.entries(guards)) {
+    test(`guard: ${name}`, async () => {
+      await assert.rejects(runWorkflow(path.join(dir, file), { args }), message, `${file} should reject (${name})`)
+    })
+  }
+}

package/skills/engineering/resolve-release/LICENSE

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

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

@@ -0,0 +1,112 @@
+---
+name: resolve-release
+description: "Release-lane orchestrator, from merge authorization to verified-in-production: assemble PRs into a release branch, cut version + CHANGELOG, promotion PR, deploy a candidate at 0% traffic, validate it, shift traffic, verify the live revision, tag and publish notes (or delete the candidate / roll back). Input is resolve-issues' handoff. NOT for driving issues to PRs (resolve-issues), pipeline debugging (cloud-build/cloud-deploy/cloud-debug), or broken production (app-debug)."
+dependencies:
+  - review-pr
+  - e2e-test
+  - ensure-coverage
+  - smoke
+---
+
+# Resolve release (authorize → merge → build candidate → validate → expose → verify)
+
+Take **merge-ready PRs** (typically a `resolve-issues` handoff) through merge, promotion and deployment to a **verified production revision**. Every other resolve-* skill stops at "do not merge unless authorized"; this one owns what follows.
+
+The **authorization is the entry gate; observed production state is the exit gate** — the loop closes on **verification of the live revision after traffic reaches it**, never on "merged" or "deploy succeeded". Production is reached in two moves: a candidate at **0% traffic**, validated there, then the shift — so most failures cost **nobody exposed, nothing to roll back, no version burned**.
+
+It **owns only** the authorization envelope, the merge/promote/validate/expose/verify sequencing, the **version identity** (bump, CHANGELOG cut, immutable tag — production promotions only), verdict routing, and rollback discipline.
+
+## How to invoke me (read first)
+
+**Before creating or resuming a release run, use `resolve-issues/scripts/run-state.mjs init|resume --skill resolve-release`.** That boundary runs `engineering-runtime`'s read-only coherence verifier first and fails closed on an incoherent, unavailable or malformed verdict; inspection commands stay available for diagnosis.
+
+**Main-loop orchestrator; never nest me in a subagent, and never fan out.** Nearly every step is outward-facing and gated on an authorization a nested or headless agent cannot collect, and a release is a serialized state machine against shared, moving targets. Run it sequentially, start to finish.
+
+**Sequential is not paused.** Wait with one background watcher launch, never a foreground poll loop. A notification is a **continuation trigger**, not a checkpoint: record it and **carry straight on in the same turn** — never write "I'll resume when the watcher reports" and end the turn (`019faea6`: three of five human interventions were that shape and decided nothing). Stop only for an authorization the envelope did not pre-approve, a terminal hand-back, or an ambiguous state. → [watching PR delivery](references/assembly.md#watching-pr-delivery)
+
+For PRs this lane opens, use [`watch-pr-delivery.mjs`](../../cicd-pipeline/mergify/scripts/watch-pr-delivery.mjs): it **observes only** — never enqueues, merges, or takes merge authorization. Other waits use their own tooling under the same one-launch rule.
+
+## Routing (read this first)
+
+**This file is an index, and must stay one** — a truncated skill silently becomes a shorter skill, and this one lost its traffic shift and rollback routing exactly that way. What must survive truncation is here; everything else is a file you read on arrival. Never work from this page alone.
+
+| Phase | Read | The rule you must not miss |
+|---|---|---|
+| **Before anything** — readiness, endpoints, tip green, the envelope | [preflight.md](references/preflight.md) · [`preflight-probes`](scripts/preflight-probes.mjs) · [`production-endpoints`](scripts/production-endpoints.mjs) · [`ensure-target-green`](scripts/ensure-target-green.mjs) | **MANDATORY**, and `unknown` is not `ok`. Repair a red target before confirmation. **No outward action until the human confirms**; undeclared deploy or identity data is a refusal. |
+| 0-2 — intake, assemble, promotion PR | [assembly.md](references/assembly.md) | Merge-readiness re-verified against the tree (principle 2); promotions **fast-forward** (principle 3). |
+| 3 — promote, build the candidate | [candidate.md](references/candidate.md) | Deploys at **0% traffic**; identity discovery **fails closed** on a missing, ambiguous or mismatched read. [Local Docker builds are not release evidence](references/principles.md#local-docker-builds-are-not-release-evidence). |
+| 4 — validate, then expose | [exposure.md](references/exposure.md) | **Approval to promote is not approval to expose.** The shift is separately authorized; identity, traffic split and verdict freshness are re-checked *after* the confirm. |
+| 5 — route on the verdict | [routing.md](references/routing.md) | Pre-exposure failure = delete the 0% candidate: no incident, no version burned. Post-exposure = the confirmed rollback policy. |
+| After a terminal step — write the handoff, profile the release | [handoff.md](references/handoff.md) · [postmortem.md](references/postmortem.md) | `report.mjs` saves the post-mortem at `done`/`discard`/`rollback` — **mandatory and automatic**, a *completeness* pass rather than a speed one. |
+| The mechanism behind a rule you are applying | [principles.md](references/principles.md) | The rules are indexed below; what enforces each is there. |
+
+**`references/why.md` is not on this list, and never is.** It is the archive — the derivation behind each rule — read when you **edit** this skill, never while running it.
+
+**Transition history:** record correlated intent/result around every outward action; state events and clocks are writer-owned. Protocol: [principles](references/principles.md) · [run state](../resolve-issues/references/run-state.md).
+
+## Non-negotiable principles
+
+The rules, verbatim. **They bind every step** — including one whose file you are reading in isolation, which is why they are here and not only in the reference. Their mechanisms: [principles.md](references/principles.md).
+
+1. **Every outward-facing action is covered by explicit authorization.**
+2. **Merge-readiness is verified against the tree, never the claim.**
+3. **Promotions fast-forward.**
+4. **Nothing the release lane runs against production mutates it — tenant or no tenant.**
+5. **The loop exits on observed production state, never on a claim.**
+6. **Rollback over live debugging — but most failures never need one.**
+7. **One release in flight per environment — the Release Attempt Lease.**
+8. **Combine into one promotion — never N individual promotions to production.**
+9. **`auto-when-green` pre-approves only behind a real gate, never on CI color alone.**
+10. **A version names a verified production SHA — and only production has versions.**
+11. **A promotion promotes a pinned candidate SHA — never a moving tip.**
+12. **The pipeline owns artifacts; the release lane owns exposure.**
+13. **An applicable gate that cannot run is a failure, not an absence.**
+14. **Where the target has durable processing, exposure is a *sequence*, not a routing change.**
+15. **Repeated failures owned by the lane's own tooling hold the version for release-design review.**
+
+## The release loop
+
+Run it sequentially; read each phase file on arrival, not before.
+
+**Emit the checkpoint summary at every step transition** — [`report.mjs <run-manifest.json>`](scripts/report.mjs). The operator's question never changes (what happened to production, what is authorized next), and rendering it from the manifest rather than from context is what survives a session dying. **A step reads `done` only when the manifest carries its evidence** — a passed marker with nothing recorded renders `undelivered`, deliberately not a synonym for done.
+
+**The repair lane: a red target gate is fixed *inside* the attempt, not by abandoning it.** [Pre-flight item 0](references/preflight.md#item-0--run-the-readiness-probes-before-proposing-anything) surfaces tip colour before the envelope is proposed and owns the whole sequence; on BLOCKED, run [`ensure-target-green.mjs`](scripts/ensure-target-green.mjs), record `release.ensureGreen`, and keep the lease held.
+
+| Step | What it does | File |
+|---|---|---|
+| — | **Pre-flight** — confirm the envelope (MANDATORY) | [preflight.md](references/preflight.md) |
+| 0 | Intake: verify merge-readiness against the tree | [assembly.md](references/assembly.md) |
+| 1 | Assemble the release (integration / release branch) | [assembly.md](references/assembly.md#1--assemble-the-release-integration--release-branch) |
+| 1b | Cut version + CHANGELOG (production promotions only) | [assembly.md](references/assembly.md#1b--cut-the-version-and-changelog-production-promotions-only) |
+| 2 | Promotion PR (`review-pr`, promotion mode) | [assembly.md](references/assembly.md#2--promotion-pr-skill-review-pr-promotion-mode) |
+| 3 | Promote, build the candidate — **0% traffic, no exposure** | [candidate.md](references/candidate.md) |
+| 4 | Validate, then **expose** (`smoke`), then the standalone display-version publication gate | [exposure.md](references/exposure.md) |
+| 5 | Route on the verdict — tag and publish only after that gate accepts; otherwise discard or roll back | [routing.md](references/routing.md) |
+
+## Definition of done (handoff report)
+
+Done means the handoff can be written from **recorded evidence**, not memory. Each item in full — including the three reported even when nothing went wrong — is [handoff.md](references/handoff.md), read at the terminal step.
+
+- **Shipped SHA** + the revision verified live, with evidence from **both phases**: candidate ALIVE at 0%; the re-check fence's readings (verdict age vs the window, the revision the candidate URL resolved to, candidate at 0%, incumbent at 100%); the serving confirmation; health after the shift — each verdict saying which evidence was **fresh** and which **carried over** ([principle 11](#non-negotiable-principles)). On a failure: the **candidate-deletion record** (pre-exposure) or **rollback record** (post-exposure).
+- **Quiescence record** — the pause order as executed, the proof's observed reading, the resume order as executed, the revision resumed against, and that resume was the **exact reverse** of pause. Where [pre-flight item 6](references/preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory) found **no durable processing, say so**: absent and declared-absent read alike otherwise.
+- **Version identity** — version, bump and why, rc tags and attempts, final tag, CHANGELOG cut commit, notes link, and whether the version was **reused** or **burned**.
+- **ensure-target-green**, the **post-release metadata PR**, **closed issues**, the **promotion PR** + fast-forward status, and the **assembly record**.
+- **Authorization audit** — the envelope, what authorized each action, human confirm vs `auto-when-green`, and `envelope.exposureIdentity` **named on every release**, with any declared weakening.
+- **Release-evidence bundle location on every terminal exit**, and on the verified path the GitHub Release it was attached to.
+- **Post-mortem** — auto-saved at a terminal step; **adjudicate each finding** and file the rendered issue. A stalled release auto-saves nothing: run it by hand.
+- Run manifest reflecting the final state.
+
+## Reference Map
+
+Phase files are the routing table above. Everything else:
+
+- **Version and tag** — [versioning.md](references/versioning.md) + [`version.mjs`](scripts/version.mjs) · [display version is not identity version](references/versioning.md#6-display-version-is-not-identity-version) + [`version-assert.mjs`](scripts/version-assert.mjs)
+- **Verified-SHA GitHub Flow** (opt-in) — [verified-sha-github-flow.md](references/verified-sha-github-flow.md#verified-sha-github-flow-mode-contract) + [`metadata-sync.mjs`](scripts/metadata-sync.mjs)
+- **Readiness before acting** — [`preflight-probes`](scripts/preflight-probes.mjs) · [`production-endpoints`](scripts/production-endpoints.mjs) · [`ensure-target-green`](scripts/ensure-target-green.mjs) ([pre-flight 0/0b](references/preflight.md#item-0--run-the-readiness-probes-before-proposing-anything))
+- **The candidate** — [`watch-candidate-delivery`](scripts/watch-candidate-delivery.mjs) (mutates nothing) · [`candidate-identity`](scripts/candidate-identity.mjs) (fail-closed discovery, attested tuple)
+- **Exposure gates** — [`green-gate`](scripts/green-gate.mjs) · [`rollback-floor`](scripts/rollback-floor.mjs) · durable processing at [principle 14](#non-negotiable-principles) + [pre-flight 6](references/preflight.md#pre-flight-gate-confirm-the-authorization-envelope-mandatory)
+- **Terminal evidence** — [`close-attempt`](scripts/close-attempt.mjs) · [`evidence-bundle`](scripts/evidence-bundle.mjs) · the report contract in [handoff.md](references/handoff.md)
+- **Holds and profiles** — [`rc-circuit-breaker`](scripts/rc-circuit-breaker.mjs) ([principle 15](#non-negotiable-principles)) · [`postmortem`](scripts/postmortem.mjs) + [postmortem.md](references/postmortem.md) · [`version-postmortem`](scripts/version-postmortem.mjs)
+- **Modes** — [auto-when-green.md](references/auto-when-green.md) (unattended promotion) · [assembly.md](references/assembly.md#1--assemble-the-release-integration--release-branch) (merge-queue repo)
+- **Other skills' seams** — [related-skills.md](references/related-skills.md)
+- **Editing this skill** — [regression-checklist.md](references/regression-checklist.md) to grade it, [why.md](references/why.md) for a rule's history. **Neither is a runtime read.**