@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/close-attempt.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// close-attempt — ordered terminal release closeout with durable evidence.
+//
+// The released path has finalize-release.mjs because it needs a larger verification transaction.
+// This command owns the corresponding failed pre-candidate path: validate the bundle and lease
+// transition, emit the immutable top-level record, then commit the manifest close. A malformed or
+// conflicting bundle leaves the attempt open, so the rc circuit breaker can never depend on an
+// operator remembering a separate emit command after recording a failure.
+
+import fs from 'node:fs'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  ATTEMPT_CLOSE_CAUSES,
+  readManifest,
+  recordReleaseAttemptState,
+  writeManifest,
+} from '../../resolve-issues/scripts/run-state.mjs'
+import { bundleKey, emitBundle, validateBundle } from './evidence-bundle.mjs'
+
+const FAILED_PRE_CANDIDATE = 'failed-pre-promotion'
+const nonEmpty = (value) => typeof value === 'string' && value.trim() !== ''
+const isObject = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+
+const USAGE = `close-attempt — close a failed pre-candidate release attempt and emit its durable bundle.
+
+Usage:
+  close-attempt.mjs <run-manifest.json> --bundle <release-evidence.json>
+    --dir <durable-evidence-dir> --state failed-pre-promotion --evidence <verified-cleanup>
+
+The command validates that the bundle belongs to the manifest's open attempt, validates the
+release-attempt close, emits the immutable top-level bundle, then writes the terminal attempt
+state. It refuses before the manifest write when the bundle is incomplete, fabricated, stale, or
+conflicts with an existing bundle for the same (attempt id, terminal state).
+
+Candidate delivery failures that end before a candidate exists use this command after the
+verified no-candidate/cleanup observation. The emitted bundle has failurePhase pre-candidate and
+is discoverable by version-postmortem.mjs and rc-circuit-breaker.mjs.`
+
+function parseArgs(argv) {
+  const positional = []
+  const options = { bundle: null, dir: null, state: null, evidence: null }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') return { help: true, positional, options }
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2)
+      if (!Object.hasOwn(options, key)) throw new Error(`unknown argument ${arg}`)
+      const value = argv[++index]
+      if (value === undefined || value.startsWith('--')) throw new Error(`${arg} needs a value`)
+      options[key] = value
+    } else {
+      positional.push(arg)
+    }
+  }
+  return { help: false, positional, options }
+}
+
+function readJson(file, label) {
+  if (!nonEmpty(file)) throw new Error(`${label} is required`)
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${label} is not readable JSON: ${file} (${error.message})`)
+  }
+}
+
+export function closeAttempt({ manifest, bundle, dir, state, evidence }) {
+  if (!isObject(manifest) || manifest.skill !== 'resolve-release') {
+    throw new Error('run manifest must be a resolve-release manifest')
+  }
+  if (state !== FAILED_PRE_CANDIDATE) {
+    throw new Error(`close-attempt only closes ${FAILED_PRE_CANDIDATE}; got ${JSON.stringify(state)}`)
+  }
+  if (!nonEmpty(dir) || !nonEmpty(evidence)) throw new Error('--dir and --evidence are required')
+
+  const attempt = manifest.release?.attempt
+  if (!isObject(attempt) || !nonEmpty(attempt.id)) throw new Error('release.attempt with an immutable id is required')
+  if (bundleKey(bundle) !== attempt.id) {
+    throw new Error(`bundle attempt id ${JSON.stringify(bundleKey(bundle))} does not match manifest attempt ${JSON.stringify(attempt.id)}`)
+  }
+  if (bundle.terminalState !== state || bundle.closedBy !== ATTEMPT_CLOSE_CAUSES[state]) {
+    throw new Error(`bundle must declare ${state}/${ATTEMPT_CLOSE_CAUSES[state]}`)
+  }
+  if (attempt.rcTag != null && bundle.rcTag !== attempt.rcTag) {
+    throw new Error('bundle rcTag does not match the manifest attempt rcTag')
+  }
+  if (manifest.envelope?.deployTrigger != null && bundle.deployTrigger !== manifest.envelope.deployTrigger) {
+    throw new Error('bundle deployTrigger does not match the manifest envelope')
+  }
+  if (manifest.release?.candidateSha != null && bundle.sha !== manifest.release.candidateSha) {
+    throw new Error('bundle sha does not match release.candidateSha')
+  }
+
+  const validation = validateBundle(bundle)
+  if (!validation.valid) throw new Error(`invalid bundle: ${validation.failed.join(', ')}`)
+  const nextManifest = recordReleaseAttemptState(manifest, { state, closedBy: ATTEMPT_CLOSE_CAUSES[state], evidence })
+  const emitted = emitBundle({ bundle, dir })
+  return { manifest: nextManifest, bundle: emitted }
+}
+
+export function main(argv) {
+  let parsed
+  try {
+    parsed = parseArgs(argv)
+    if (parsed.help) {
+      console.log(USAGE)
+      return 0
+    }
+    if (parsed.positional.length !== 1) throw new Error('exactly one run-manifest path is required')
+    const { bundle, dir, state, evidence } = parsed.options
+    const manifestPath = parsed.positional[0]
+    const result = closeAttempt({
+      manifest: readJson(manifestPath, 'run manifest'),
+      bundle: readJson(bundle, 'bundle'),
+      dir,
+      state,
+      evidence,
+    })
+    writeManifest(manifestPath, result.manifest)
+    process.stdout.write(JSON.stringify({
+      attemptId: result.manifest.release.attempt.id,
+      state: result.manifest.release.attempt.state,
+      bundle: result.bundle,
+    }, null, 2) + '\n')
+    return 0
+  } catch (error) {
+    console.error(`close-attempt: ${error.message}\n\n${USAGE}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2))
+}

package/skills/engineering/resolve-release/scripts/closeout-release.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// closeout-release — the one released-path closeout command (#1025).
+//
+// A release cannot report success until every durable record is present: the finalizer writes the
+// terminal manifest state, this command emits then re-validates its immutable bundle, copies the
+// aggregate artifact, and persists both post-mortems. The normal path assembles the bundle from
+// manifest observations plus build/approval receipts; it never accepts a hand-authored bundle.
+
+import fs from 'node:fs'
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { readManifest, writeManifest } from '../../resolve-issues/scripts/run-state.mjs'
+import { finalizeRelease } from './finalize-release.mjs'
+import { emitBundle, validateBundle } from './evidence-bundle.mjs'
+import { releaseVersion, saveReleasePostmortem } from './postmortem.mjs'
+import { saveVersionPostmortem, versionPostmortem } from './version-postmortem.mjs'
+
+const nonEmpty = (value) => typeof value === 'string' && value.trim() !== ''
+
+const USAGE = `closeout-release — finalize one verified release and write every terminal artifact.
+
+Usage:
+  closeout-release.mjs --manifest <run-manifest.json>
+    --adapter-completion-artifact <immutable-completion.json>
+    --adapter-component-head <40-hex-component-head>
+    --adapter-completion-sha256 <64-hex-sha256>
+    --build-identity <build-identity.json> --approval <approval.json>
+    [--durable-processing <durable-processing-receipts.json>]
+    --aggregate-bundle <release-evidence.json> --postmortem-dir <dir> [--now <iso>]
+
+Sequence: finalize manifest -> emit bundle -> validate bundle -> copy aggregate bundle -> save
+run + version post-mortems. Any failed step exits nonzero and prints no success response. The
+normal path assembles the bundle from recorded observations; hand-written bundles are recovery
+artifacts only and must be validated with evidence-bundle.mjs before use.`
+
+function readJson(file, label) {
+  if (!nonEmpty(file)) throw new Error(`--${label} is required`)
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${label} is not readable JSON: ${file} (${error.message})`)
+  }
+}
+
+function parse(argv) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') return { help: true }
+    if (!arg.startsWith('--')) throw new Error(`unexpected positional argument ${arg}`)
+    const key = arg.slice(2)
+    if (!['manifest', 'adapter-completion-artifact', 'adapter-component-head', 'adapter-completion-sha256',
+      'build-identity', 'approval', 'durable-processing', 'aggregate-bundle', 'postmortem-dir', 'now'].includes(key)) {
+      throw new Error(`unknown argument ${arg}`)
+    }
+    const value = argv[++index]
+    if (!nonEmpty(value) || value.startsWith('--')) throw new Error(`${arg} needs a value`)
+    options[key] = value
+  }
+  for (const key of ['manifest', 'adapter-completion-artifact', 'adapter-component-head',
+    'adapter-completion-sha256', 'build-identity', 'approval', 'aggregate-bundle', 'postmortem-dir']) {
+    if (!nonEmpty(options[key])) throw new Error(`--${key} is required`)
+  }
+  return { options }
+}
+
+function releaseBundle(manifest, buildIdentity, approval, durableProcessing) {
+  const release = manifest.release ?? {}
+  const attempt = release.attempt ?? {}
+  const candidate = release.candidateIdentity
+  const declaredDurableProcessing = manifest.envelope?.durableProcessing
+  if (declaredDurableProcessing?.present === true && !durableProcessing) {
+    throw new Error('durable-processing receipts are required when the release declares durable processing')
+  }
+  return {
+    attemptId: attempt.id,
+    rcTag: release.rcTag ?? attempt.rcTag,
+    deployTrigger: manifest.envelope?.deployTrigger,
+    sha: manifest.shippedSha,
+    buildIdentity,
+    terminalState: 'released',
+    closedBy: 'verified-release',
+    candidateReceipt: candidate,
+    candidateVerdict: release.candidateVerdict,
+    approval,
+    trafficTransition: {
+      from: release.previousRevision,
+      to: candidate?.revision,
+      fromPercent: release.servingConfirmation?.previousRevisionPercent,
+      toPercent: release.servingConfirmation?.candidatePercent,
+    },
+    liveVerdict: release.liveVerdict,
+    durableProcessing: durableProcessing ?? { present: false },
+  }
+}
+
+function savePostmortems(manifest, postmortemDir) {
+  const env = { ...process.env, RESOLVER_POSTMORTEM_DIR: postmortemDir }
+  const run = saveReleasePostmortem(manifest, env)
+  if (!run.saved) throw new Error(`run post-mortem was not saved: ${run.error ?? 'unknown error'}`)
+
+  const version = releaseVersion(manifest)
+  if (!nonEmpty(version) || !nonEmpty(manifest.durableEvidenceDir)) {
+    throw new Error('version post-mortem requires a release version and durableEvidenceDir')
+  }
+  const profile = versionPostmortem({ dir: manifest.durableEvidenceDir, version, runSlug: manifest.runSlug })
+  if (profile.attempts.length === 0) throw new Error('version post-mortem found no durable bundles after emission')
+  const aggregate = saveVersionPostmortem(profile, env)
+  if (!aggregate.saved) throw new Error(`version post-mortem was not saved: ${aggregate.error ?? 'unknown error'}`)
+  return { run: run.paths, version: aggregate.paths }
+}
+
+export function closeoutRelease(options) {
+  const before = readManifest(options.manifest)
+  const result = finalizeRelease(before, {
+    now: options.now ?? new Date().toISOString(),
+    adapterCompletionArtifact: options['adapter-completion-artifact'],
+    adapterComponentHead: options['adapter-component-head'],
+    adapterCompletionSha256: options['adapter-completion-sha256'],
+  })
+  if (!result.resumed) writeManifest(options.manifest, result.manifest)
+
+  const buildIdentity = readJson(options['build-identity'], 'build-identity')
+  const approval = readJson(options.approval, 'approval')
+  const durableProcessing = options['durable-processing']
+    ? readJson(options['durable-processing'], 'durable-processing')
+    : null
+  const bundle = releaseBundle(result.manifest, buildIdentity, approval, durableProcessing)
+  const emitted = emitBundle({ bundle, dir: result.manifest.durableEvidenceDir })
+  const written = readJson(emitted.path, 'emitted bundle')
+  const validation = validateBundle(written)
+  if (!validation.valid) throw new Error(`emitted bundle did not validate: ${validation.failed.join(', ')}`)
+
+  fs.copyFileSync(emitted.path, options['aggregate-bundle'])
+  const postmortems = savePostmortems(result.manifest, options['postmortem-dir'])
+  return {
+    ok: true,
+    manifest: options.manifest,
+    bundle: emitted.path,
+    aggregateBundle: options['aggregate-bundle'],
+    postmortems,
+    steps: { finalize: 'passed', emit: 'passed', validate: 'passed', aggregateCopy: 'passed', postmortems: 'passed' },
+  }
+}
+
+export function main(argv) {
+  try {
+    const parsed = parse(argv)
+    if (parsed.help) {
+      console.log(USAGE)
+      return 0
+    }
+    console.log(JSON.stringify(closeoutRelease(parsed.options), null, 2))
+    return 0
+  } catch (error) {
+    console.error(`closeout-release: ${error.message}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = main(process.argv.slice(2))

package/skills/engineering/resolve-release/scripts/doctrine.mjs

@@ -0,0 +1,106 @@
+// The release doctrine as ONE document, however it happens to be split across files.
+//
+// Why this exists: SKILL.md used to be the whole doctrine — 490 lines, 129KB — and the
+// doctrine tests in this directory read it directly and slice it by heading. Then a real
+// failure showed up: an agent harness loaded the skill and got lines 1-260 of 491, which cut
+// off step 4 (the traffic shift), step 5 (rollback routing), and the Reference Map that would
+// have told it where to look. Nothing warned anyone; the model simply never received the
+// second half of a production-release procedure.
+//
+// The fix was to make SKILL.md an index and move each phase into `references/`. That kept
+// every word (the sections were extracted verbatim), but it broke the premise the tests were
+// written on — that "the doctrine" and "SKILL.md" are the same string.
+//
+// They were never the same thing, and that is the point. These tests grade the *doctrine*:
+// that a passage exists, that two rules appear in a required order, that a slice stops at its
+// sibling. All of that is preserved by a move; none of it is a claim about which file the prose
+// sits in. So the doctrine is reassembled here, in its original document order, and the tests
+// read it from this module instead of from a path.
+//
+// The reassembly is faithful rather than approximate: each phase file was extracted as a
+// contiguous line range, in order, so concatenating them in that order reproduces the original
+// document. Two details make it exact:
+//
+//   1. Each reference file opens with a NEW `# Title` and orientation paragraph that did not
+//      exist in the original. Those are stripped — the body resumes at the first heading that
+//      came from the original document, which is why each entry below names it.
+//   2. SKILL.md now carries a `## Non-negotiable principles` heading of its own, holding the
+//      14 rules as a one-line index. Concatenating SKILL.md whole would put that index ahead of
+//      the real section and every principle-body slice would land in the index instead. So
+//      SKILL.md contributes only its head (frontmatter → Related skills) and its tail
+//      (Definition of done onward); the principles section comes from `principles.md`.
+//
+// If a future split moves a section again, update the ORDER table below in the same commit.
+// A test that fails because prose moved is this module being out of date, not doctrine being
+// lost — but do confirm which of the two it is before editing anything here.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const skillDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const read = (rel) => fs.readFileSync(path.join(skillDir, rel), 'utf8')
+
+// Each phase file, and the first heading in it that came from the original SKILL.md. Everything
+// above that heading is this-file-only orientation and is dropped.
+const ORDER = [
+  { file: 'references/principles.md', resumeAt: '## Non-negotiable principles' },
+  { file: 'references/preflight.md', resumeAt: '## Pre-flight gate: confirm the authorization envelope' },
+  { file: 'references/assembly.md', resumeAt: '### 0 — Intake' },
+  { file: 'references/candidate.md', resumeAt: '### 3 — Promote' },
+  { file: 'references/exposure.md', resumeAt: '### 4 — Validate' },
+  { file: 'references/routing.md', resumeAt: '### 5 — Route' },
+  // The handoff report moved off SKILL.md (2026-08-17); the doctrine follows it.
+  { file: 'references/handoff.md', resumeAt: '## Every item' },
+]
+
+function bodyFrom({ file, resumeAt }) {
+  const text = read(file)
+  const idx = text.indexOf(`\n${resumeAt}`)
+  if (idx < 0) {
+    throw new Error(
+      `doctrine.mjs: ${file} no longer contains "${resumeAt}". Either the heading was reworded ` +
+      '(update ORDER in this file, same commit) or the section was moved again (update ORDER, ' +
+      'and check the section still exists somewhere before assuming it is only a rename).',
+    )
+  }
+  return text.slice(idx + 1)
+}
+
+// SKILL.md's own contribution: its head, and its tail from Definition of done onward. The
+// sections between those two — the routing index, the principles INDEX, the loop table — are
+// navigation this module deliberately excludes, because the doctrine they point at is included
+// in full from the files above and a duplicate heading would capture every slice.
+function skillHeadAndTail() {
+  const text = read('SKILL.md')
+  const headEnd = text.indexOf('\n## Routing')
+  const tailStart = text.indexOf('\n## Definition of done')
+  if (headEnd < 0 || tailStart < 0) {
+    throw new Error(
+      'doctrine.mjs: SKILL.md is missing "## Routing" or "## Definition of done". Both are ' +
+      'structural — Routing is the index that has to survive a truncated load, and Definition ' +
+      'of done is graded prose. Restore the heading, or update this loader in the same commit.',
+    )
+  }
+  return { head: text.slice(0, headEnd), tail: text.slice(tailStart) }
+}
+
+// `## The release loop` opened the step sequence in the original document and now lives only in
+// SKILL.md's navigation table, so it is reinserted at its original position — before step 0, not
+// after step 5. Order is load-bearing here: several tests assert that one rule appears before
+// another, and they would read a shuffled reassembly as a doctrine defect.
+const LOOP_HEADING_BEFORE = 'references/assembly.md'
+
+export function loadDoctrine() {
+  const { head, tail } = skillHeadAndTail()
+  const parts = [head]
+  for (const entry of ORDER) {
+    if (entry.file === LOOP_HEADING_BEFORE) parts.push('## The release loop')
+    parts.push(bodyFrom(entry))
+  }
+  parts.push(tail)
+  return parts.join('\n')
+}
+
+// The assembled doctrine. Named `SKILL` at the call sites for continuity with the tests that
+// already sliced a variable by that name — the string is what they were always asserting about.
+export const DOCTRINE = loadDoctrine()