@1aboveio/skills 0.19.2 → 0.20.1

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

@@ -1,135 +0,0 @@
-#!/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

@@ -1,161 +0,0 @@
-#!/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

@@ -1,106 +0,0 @@
-// 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()