@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/engineering-runtime/scripts/head-check-set.mjs

@@ -0,0 +1,398 @@
+// head-check-set — the FULL observed state of one commit, not the named subset of it.
+//
+// A required-check plan answers "are the checks I named green?". #1081 is what that
+// question cannot see. Two release workflows were rejected by GitHub at validation
+// time; every push produced two runs that completed in the same second having executed
+// ZERO jobs, named after the file path instead of the declared `name:`. That was
+// visible for seven hours across fourteen commits, and the unit still earned an
+// independent PASS and a merge-ready mark, because the one check anybody read
+// (`skill-script-tests`) was green — and it genuinely was.
+//
+// THE SUBTLETY THAT DEFEATS THE OBVIOUS FIX. "Read every check-run instead of the
+// named ones" would ALSO have missed #1081. A workflow GitHub cannot parse produces no
+// check-run at all — not a red one, none. The real observation at that SHA:
+//
+//   GET /commits/ee5dd91a…/check-runs  → 4 entries, every one success/neutral/skipped
+//   GET /commits/ee5dd91a…/status      → state "pending", zero statuses
+//   GET /actions/runs?head_sha=ee5dd91a… → 3 runs, TWO of them conclusion "failure"
+//                                          with name == path and zero jobs
+//
+// So the full state of a commit is the union of three channels — check-runs, legacy
+// commit statuses, and Actions runs — and the third is the only one where a startup
+// failure lives. This module classifies that union. Both halves are load-bearing: the
+// union is what makes undeclared red visible, and the zero-job run is what makes the
+// #1081 class NAMEABLE rather than a number in a count.
+//
+// WHAT THIS DELIBERATELY DOES NOT DO. It does not gate. Whether a red check nobody
+// declared required should block a merge is a policy decision belonging to the human
+// and to `.mergify.yml`, and a reporting script that quietly changed what merges would
+// be a worse defect than the one it fixes. The partition names `undeclaredRed`
+// separately from `requiredRed` precisely so a caller can act on the difference; the
+// only outcome this module calls failing is the one the existing contract already
+// blocks on — a REQUIRED check red or absent.
+
+export const HEAD_CHECK_SET_VERSION = 1
+export const HEAD_CHECK_SET_KIND = 'head-check-set'
+export const OBSERVATION_SOURCES = Object.freeze(['check-run', 'commit-status', 'actions-run'])
+export const OBSERVATION_STATES = Object.freeze(['green', 'red', 'neutral', 'pending'])
+
+// Why `cancelled` counts as red: a cancelled required check is not a passed one, and
+// the surrounding contract has said "skipped is never success" since epic-892. Neutral
+// and skipped stay `neutral` — they are not passes either, but they are not evidence of
+// breakage, and conflating the two is how a report gets ignored.
+const RED_CONCLUSIONS = new Set(['failure', 'timed_out', 'action_required', 'startup_failure', 'stale', 'cancelled'])
+const NEUTRAL_CONCLUSIONS = new Set(['skipped', 'neutral'])
+const COMPLETED = new Set(['completed'])
+
+// A run GitHub could not parse is reported with its file path where its name belongs,
+// because there is no parsed `name:` to report. Corroborating, never sufficient: a
+// workflow may legitimately declare no `name:`, in which case GitHub also uses the path.
+const WORKFLOW_PATH = /^\.github\/workflows\/[^/]+\.ya?ml$/
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+const SHA = /^[0-9a-f]{40}$/i
+const lower = (value) => (value == null ? null : String(value).toLowerCase())
+
+function stateOf(status, conclusion) {
+  const normalizedStatus = lower(status)
+  const normalizedConclusion = lower(conclusion)
+  if (normalizedStatus !== null && !COMPLETED.has(normalizedStatus)) return 'pending'
+  if (normalizedConclusion === null) return 'pending'
+  if (normalizedConclusion === 'success') return 'green'
+  if (NEUTRAL_CONCLUSIONS.has(normalizedConclusion)) return 'neutral'
+  if (RED_CONCLUSIONS.has(normalizedConclusion)) return 'red'
+  // Deny-by-default on a conclusion this module has never seen: an unknown conclusion
+  // read as green is exactly the failure this file exists to remove.
+  return 'red'
+}
+
+function commitStatusState(state) {
+  const normalized = lower(state)
+  if (normalized === 'success') return 'green'
+  if (normalized === 'pending') return 'pending'
+  return 'red'
+}
+
+/** Every check name the plan declares required, in any phase. */
+export function requiredCheckNames(plan) {
+  const fromChecks = (plan?.checks || [])
+    .filter((check) => check?.admission === 'required' && nonEmpty(check?.name))
+    .map((check) => check.name)
+  const fromDiscovery = (plan?.discovery?.requiredChecks || []).filter(nonEmpty)
+  return [...new Set([...fromChecks, ...fromDiscovery])].sort()
+}
+
+function checkRunObservation(run) {
+  return {
+    source: 'check-run',
+    name: String(run?.name ?? ''),
+    state: stateOf(run?.status, run?.conclusion),
+    status: run?.status ?? null,
+    conclusion: run?.conclusion ?? null,
+    app: run?.app?.slug ?? null,
+    checkSuiteId: run?.check_suite?.id ?? null,
+    url: run?.html_url ?? null,
+  }
+}
+
+function commitStatusObservation(status) {
+  return {
+    source: 'commit-status',
+    name: String(status?.context ?? ''),
+    state: commitStatusState(status?.state),
+    status: 'completed',
+    conclusion: status?.state ?? null,
+    app: status?.creator?.login ?? null,
+    checkSuiteId: null,
+    url: status?.target_url ?? null,
+  }
+}
+
+/**
+ * An Actions run, plus the two facts that make #1081 nameable.
+ *
+ * `jobCount` is supplied by the caller because it costs one extra API call per run and
+ * this module is pure. A run that has completed with `jobCount === 0` executed nothing:
+ * that is the startup-failure signature, and it is the whole reason the Actions channel
+ * is read at all. `null` means the caller could not determine it — reported as unknown,
+ * never as zero, because "we did not look" and "there were none" must not render alike.
+ */
+function actionsRunObservation(run) {
+  const name = String(run?.name ?? '')
+  const path = run?.path ?? null
+  const jobCount = Number.isInteger(run?.jobCount) ? run.jobCount : null
+  const state = stateOf(run?.status, run?.conclusion)
+  const completed = COMPLETED.has(lower(run?.status) ?? '')
+  return {
+    source: 'actions-run',
+    name,
+    state,
+    status: run?.status ?? null,
+    conclusion: run?.conclusion ?? null,
+    app: 'github-actions',
+    checkSuiteId: run?.check_suite_id ?? null,
+    url: run?.html_url ?? null,
+    runId: run?.id ?? null,
+    path,
+    event: run?.event ?? null,
+    jobCount,
+    // Recorded, never classified on. The obvious reading of "is this run attached to the
+    // pull request?" is the API's `pull_requests` array, and it is not usable: at
+    // ee5dd91a the perfectly healthy `pull_request`-event `Skill gates` run also carries
+    // `pull_requests: []`. Deriving an attachment boolean from it would report every
+    // healthy run as unattached. `event` is what actually distinguishes an out-of-band
+    // dispatch, and it is what `absenceReason` uses.
+    pullRequests: Array.isArray(run?.pull_requests) ? run.pull_requests.map((entry) => entry?.number ?? null) : [],
+    nameEqualsPath: nonEmpty(path) && name === path,
+    looksLikeWorkflowPath: WORKFLOW_PATH.test(name),
+    zeroJobs: completed && jobCount === 0,
+  }
+}
+
+/** Raw Actions runs (each optionally carrying an integer `jobCount`) as observations. */
+export function observeActionsRuns(runs) {
+  return (Array.isArray(runs) ? runs : []).map(actionsRunObservation)
+}
+
+/**
+ * The #1081 signature: a run that COMPLETED, executed zero jobs, and did not succeed.
+ *
+ * Kept distinct from "a red run" on purpose. A red run with jobs failed while doing its
+ * work and its jobs say why; a red run with no jobs never started, and nothing else in
+ * the system says so — no check-run exists to be red. The name-equals-path corroboration
+ * is reported alongside rather than required, because a workflow with no declared `name:`
+ * produces the same coincidence honestly.
+ */
+export function startupFailures(observations) {
+  return observations
+    .filter((entry) => entry.source === 'actions-run' && entry.zeroJobs && entry.state !== 'green')
+    .map((entry) => ({
+      runId: entry.runId,
+      name: entry.name,
+      path: entry.path,
+      event: entry.event,
+      conclusion: entry.conclusion,
+      state: entry.state,
+      nameEqualsPath: entry.nameEqualsPath,
+      looksLikeWorkflowPath: entry.looksLikeWorkflowPath,
+      url: entry.url,
+    }))
+}
+
+/**
+ * Why a required check produced no observation at all. This is #1058's distinction and
+ * it falls out of the same union: the three answers call for opposite responses, and the
+ * single string they share today ("no workflow run found") reads as *still queued* for
+ * all three.
+ */
+export function ciAbsence(observations) {
+  const actionsRuns = (observations || []).filter((entry) => entry.source === 'actions-run')
+  return absenceReason(observations || [], actionsRuns)
+}
+
+function absenceReason(observations, actionsRuns) {
+  if (observations.some((entry) => entry.state === 'pending')) {
+    return {
+      reason: 'pending',
+      detail: 'a run for this SHA has not finished; waiting is correct and dispatching another would waste a run',
+    }
+  }
+  if (observations.length === 0) {
+    return {
+      reason: 'no-run-anywhere',
+      detail: 'no check-run, commit status or Actions run exists for this SHA — the triggering event was most likely never delivered; waiting is futile, a workflow_dispatch or a close/reopen at the same head is the intervention',
+    }
+  }
+  // #1058's third state: a run exists at this SHA, but it got there by hand. The check
+  // it produced is honest exact-head evidence and satisfies no merge-queue condition,
+  // and the situation is actionable NOW rather than something to wait out.
+  const dispatched = actionsRuns.filter((entry) => entry.event === 'workflow_dispatch')
+  if (dispatched.length && dispatched.length === actionsRuns.length) {
+    return {
+      reason: 'dispatched-out-of-band',
+      detail: `every Actions run at this SHA was started by workflow_dispatch (${dispatched.map((entry) => entry.runId).join(', ')}) — the event that would have created this check was never delivered; the dispatched run is honest exact-head evidence but satisfies no merge-queue check condition, so delivery still needs the event`,
+    }
+  }
+  return {
+    reason: 'absent-though-runs-completed',
+    detail: 'runs for this SHA have completed without ever producing this check — inspect the workflow trigger and path filters, and the startupFailures channel: a workflow GitHub refuses to parse creates a run and produces no check-run at all',
+  }
+}
+
+/**
+ * Classify the full observed state of one head SHA.
+ *
+ * @param {object} input
+ * @param {string} input.repository            owner/name
+ * @param {string} input.headSha               the 40-character commit being described
+ * @param {object[]} [input.checkRuns]         raw `GET /commits/{sha}/check-runs` entries
+ * @param {object[]} [input.statuses]          raw `GET /commits/{sha}/status` `.statuses` entries
+ * @param {object[]} [input.actionsRuns]       raw `GET /actions/runs?head_sha=` entries, each
+ *                                             optionally carrying an integer `jobCount`
+ * @param {object|null} [input.plan]           a required-check plan; OPTIONAL — with none, nothing
+ *                                             is required and this degrades to a pure observation
+ *                                             report rather than calling every red undeclared
+ * @param {string} [input.collectedAt]
+ */
+export function classifyHeadCheckSet({
+  repository,
+  headSha,
+  checkRuns = [],
+  statuses = [],
+  actionsRuns = [],
+  plan = null,
+  collectedAt = new Date().toISOString(),
+}) {
+  const observations = [
+    ...checkRuns.map(checkRunObservation),
+    ...statuses.map(commitStatusObservation),
+    ...actionsRuns.map(actionsRunObservation),
+  ]
+  const required = requiredCheckNames(plan)
+  const requiredSet = new Set(required)
+  for (const entry of observations) entry.required = requiredSet.has(entry.name)
+
+  const observedNames = new Set(observations.map((entry) => entry.name))
+  const actionsObservations = observations.filter((entry) => entry.source === 'actions-run')
+
+  const red = observations.filter((entry) => entry.state === 'red')
+  const partition = {
+    requiredRed: red.filter((entry) => entry.required),
+    // The #1081 case. Informational by contract — see this file's header — but never silent.
+    undeclaredRed: red.filter((entry) => !entry.required),
+    neverRan: required
+      .filter((name) => !observedNames.has(name))
+      .map((name) => ({ name, ...absenceReason(observations, actionsObservations) })),
+    pending: observations.filter((entry) => entry.state === 'pending'),
+    neutral: observations.filter((entry) => entry.state === 'neutral'),
+    green: observations.filter((entry) => entry.state === 'green'),
+  }
+  const signatures = { startupFailures: startupFailures(observations) }
+
+  // Outcome ordering is the caller's decision order, and `green-with-undeclared-red` is
+  // deliberately its own value rather than folded into either neighbour: it is the state
+  // #1081 was in for seven hours, and it must be neither "failure" (it does not block)
+  // nor "green" (it is not).
+  let outcome = 'green'
+  if (partition.requiredRed.length) outcome = 'required-red'
+  else if (partition.neverRan.length) outcome = 'required-missing'
+  else if (partition.pending.length) outcome = 'pending'
+  else if (partition.undeclaredRed.length || signatures.startupFailures.length) outcome = 'green-with-undeclared-red'
+
+  return {
+    version: HEAD_CHECK_SET_VERSION,
+    kind: HEAD_CHECK_SET_KIND,
+    repository,
+    headSha,
+    collectedAt,
+    planned: { required, planPresent: plan != null },
+    observations,
+    signatures,
+    partition,
+    summary: {
+      outcome,
+      counts: {
+        observations: observations.length,
+        checkRuns: checkRuns.length,
+        commitStatuses: statuses.length,
+        actionsRuns: actionsRuns.length,
+        requiredRed: partition.requiredRed.length,
+        undeclaredRed: partition.undeclaredRed.length,
+        neverRan: partition.neverRan.length,
+        pending: partition.pending.length,
+        startupFailures: signatures.startupFailures.length,
+      },
+    },
+  }
+}
+
+/**
+ * True when the REQUIRED set — and only the required set — is unsatisfied.
+ *
+ * This is the whole of the blocking judgement, isolated here so that the one place a
+ * caller could turn undeclared red into a merge decision is a single named function
+ * rather than an exit-code expression buried in a CLI.
+ */
+export function blocksOnRequiredSet(artifact) {
+  return (artifact?.partition?.requiredRed?.length ?? 0) > 0
+    || (artifact?.partition?.neverRan?.length ?? 0) > 0
+}
+
+export function validateHeadCheckSetArtifact(artifact, { expectedHeadSha, label = 'headCheckSet' } = {}) {
+  const errors = []
+  if (!isObject(artifact)) return { ok: false, errors: [`${label} must be an object`] }
+  if (artifact.version !== HEAD_CHECK_SET_VERSION) errors.push(`${label}.version must be ${HEAD_CHECK_SET_VERSION}`)
+  if (artifact.kind !== HEAD_CHECK_SET_KIND) errors.push(`${label}.kind must be "${HEAD_CHECK_SET_KIND}"`)
+  if (!nonEmpty(artifact.repository) || !/^[^/\s]+\/[^/\s]+$/.test(artifact.repository)) errors.push(`${label}.repository must be owner/name`)
+  if (!nonEmpty(artifact.headSha) || !SHA.test(artifact.headSha)) errors.push(`${label}.headSha must be a full 40-character commit SHA`)
+  else if (expectedHeadSha && artifact.headSha !== expectedHeadSha) errors.push(`${label} is STALE: stamped ${artifact.headSha}, expected ${expectedHeadSha}`)
+  if (!Array.isArray(artifact.observations)) errors.push(`${label}.observations must be an array`)
+  else {
+    for (const [index, entry] of artifact.observations.entries()) {
+      const at = `${label}.observations[${index}]`
+      if (!isObject(entry)) { errors.push(`${at} must be an object`); continue }
+      if (!OBSERVATION_SOURCES.includes(entry.source)) errors.push(`${at}.source must be ${OBSERVATION_SOURCES.join('|')}`)
+      if (!nonEmpty(entry.name)) errors.push(`${at}.name must be a non-empty string`)
+      if (!OBSERVATION_STATES.includes(entry.state)) errors.push(`${at}.state must be ${OBSERVATION_STATES.join('|')}`)
+      if (typeof entry.required !== 'boolean') errors.push(`${at}.required must be boolean`)
+    }
+  }
+  if (!isObject(artifact.partition)) errors.push(`${label}.partition must be an object`)
+  else {
+    for (const key of ['requiredRed', 'undeclaredRed', 'neverRan', 'pending', 'neutral', 'green']) {
+      if (!Array.isArray(artifact.partition[key])) errors.push(`${label}.partition.${key} must be an array`)
+    }
+    for (const [index, entry] of (artifact.partition.neverRan || []).entries()) {
+      const at = `${label}.partition.neverRan[${index}]`
+      if (!isObject(entry) || !nonEmpty(entry.name)) errors.push(`${at}.name must be a non-empty string`)
+      // The reason is the entire point of the row: an absence without one reads as
+      // "still queued" for all three of #1058's cases.
+      else if (!nonEmpty(entry.reason) || !nonEmpty(entry.detail)) errors.push(`${at} requires an actionable reason and detail`)
+    }
+  }
+  if (!isObject(artifact.signatures) || !Array.isArray(artifact.signatures.startupFailures)) errors.push(`${label}.signatures.startupFailures must be an array`)
+  if (!isObject(artifact.summary) || !nonEmpty(artifact.summary.outcome)) errors.push(`${label}.summary.outcome must be a non-empty string`)
+  return { ok: errors.length === 0, errors }
+}
+
+function describe(entry) {
+  const detail = entry.source === 'actions-run'
+    ? ` — run ${entry.runId ?? '?'}, event ${entry.event ?? '?'}, ${entry.jobCount === null ? 'job count unknown' : `${entry.jobCount} job(s)`}`
+    : ''
+  return `${entry.name} [${entry.source}] ${entry.conclusion ?? entry.status ?? 'pending'}${detail}`
+}
+
+export function renderHeadCheckSet(artifact) {
+  const lines = [
+    '<!-- generated by head-check-set.mjs — do not hand-edit; re-run collect -->',
+    `**Full check set at \`${artifact.headSha}\`** (${artifact.repository}, collected ${artifact.collectedAt})`,
+    '',
+    `- Outcome: **${artifact.summary?.outcome}** — ${artifact.summary?.counts?.observations ?? 0} observation(s) across `
+      + `${artifact.summary?.counts?.checkRuns ?? 0} check-run(s), ${artifact.summary?.counts?.commitStatuses ?? 0} commit status(es), `
+      + `${artifact.summary?.counts?.actionsRuns ?? 0} Actions run(s)`,
+    `- Required by the plan: ${artifact.planned?.planPresent ? (artifact.planned.required.join(', ') || 'none') : 'NO PLAN SUPPLIED — nothing is classified required, so this is an observation report only'}`,
+  ]
+  const section = (title, rows) => {
+    if (!rows.length) return
+    lines.push(`- ${title}:`)
+    for (const row of rows) lines.push(`  - ${row}`)
+  }
+  section('REQUIRED and red (blocking under the existing contract)', artifact.partition?.requiredRed?.map(describe) ?? [])
+  section(
+    'NOT required and red (informational — surfaced, never gated here; whether it should block belongs to `.mergify.yml` and the human)',
+    artifact.partition?.undeclaredRed?.map(describe) ?? [],
+  )
+  section(
+    'Required but never ran at all',
+    artifact.partition?.neverRan?.map((row) => `${row.name}: ${row.reason} — ${row.detail}`) ?? [],
+  )
+  section(
+    'Workflow runs that completed having executed ZERO jobs (the #1081 startup-failure signature)',
+    artifact.signatures?.startupFailures?.map((row) =>
+      `run ${row.runId} \`${row.name}\` (${row.conclusion}) executed no jobs`
+      + `${row.nameEqualsPath ? ' and its name equals its file path — corroborating a workflow GitHub refused to parse' : ''}`) ?? [],
+  )
+  section('Pending', artifact.partition?.pending?.map(describe) ?? [])
+  return lines.join('\n')
+}

package/skills/engineering/engineering-runtime/scripts/invocation-policy.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { isMainModule } from './main-module.mjs';
+
+export const MANUAL_ONLY = 'manual-only';
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function frontmatterBounds(contents) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(contents);
+  if (!match) throw new Error('SKILL.md must begin with YAML frontmatter');
+  return { body: match[1], end: match[0].length };
+}
+
+function manualOnlySkill(contents) {
+  const frontmatter = frontmatterBounds(contents);
+  const declarations = frontmatter.body.match(/^disable-model-invocation\s*:\s*.*$/gm) ?? [];
+  if (declarations.length > 1) throw new Error('SKILL.md repeats disable-model-invocation');
+
+  const body = declarations.length === 1
+    ? frontmatter.body.replace(/^disable-model-invocation\s*:\s*.*$/m, 'disable-model-invocation: true')
+    : `${frontmatter.body}\ndisable-model-invocation: true`;
+  return `---\n${body}\n---\n${contents.slice(frontmatter.end)}`;
+}
+
+function manualOnlyOpenAi(contents) {
+  const policyHeaders = contents.match(/^policy\s*:\s*$/gm) ?? [];
+  if (policyHeaders.length > 1) throw new Error('agents/openai.yaml repeats policy');
+  if (policyHeaders.length === 0) {
+    const prefix = contents.length === 0 || contents.endsWith('\n') ? contents : `${contents}\n`;
+    return `${prefix}policy:\n  allow_implicit_invocation: false\n`;
+  }
+
+  const lines = contents.split('\n');
+  const policyIndex = lines.findIndex((line) => /^policy\s*:\s*$/.test(line));
+  let policyEnd = lines.length;
+  for (let index = policyIndex + 1; index < lines.length; index += 1) {
+    if (/^[^\s#][^:]*\s*:/.test(lines[index])) {
+      policyEnd = index;
+      break;
+    }
+  }
+  const declarations = lines
+    .slice(policyIndex + 1, policyEnd)
+    .filter((line) => /^\s+allow_implicit_invocation\s*:/.test(line));
+  if (declarations.length > 1) throw new Error('agents/openai.yaml repeats policy.allow_implicit_invocation');
+  if (declarations.length === 1) {
+    return lines.map((line, index) => (
+      index > policyIndex && index < policyEnd && /^\s+allow_implicit_invocation\s*:/.test(line)
+        ? '  allow_implicit_invocation: false'
+        : line
+    )).join('\n');
+  }
+  lines.splice(policyIndex + 1, 0, '  allow_implicit_invocation: false');
+  return lines.join('\n');
+}
+
+export function manualOnlyPolicyFindings(skillDirectory) {
+  const findings = [];
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+  if (!existsSync(skillPath)) return ['SKILL.md is missing'];
+  const skill = readFileSync(skillPath, 'utf8');
+  const declarations = frontmatterBounds(skill).body.match(/^disable-model-invocation\s*:\s*true\s*$/gm) ?? [];
+  if (declarations.length !== 1) findings.push('SKILL.md must declare disable-model-invocation: true exactly once');
+  if (!existsSync(openaiPath)) {
+    findings.push('agents/openai.yaml is missing');
+  } else {
+    const openai = readFileSync(openaiPath, 'utf8');
+    const policies = openai.match(/^policy\s*:\s*$/gm) ?? [];
+    const implicit = openai.match(/^\s+allow_implicit_invocation\s*:\s*false\s*$/gm) ?? [];
+    if (policies.length !== 1 || implicit.length !== 1) {
+      findings.push('agents/openai.yaml must declare policy.allow_implicit_invocation: false exactly once');
+    }
+  }
+  return findings;
+}
+
+// Restore the reviewed upstream bytes for source-integrity hashing. The installed tree must first
+// pass manualOnlyPolicyFindings; these exact trailing additions are the only intentional divergence.
+export function reviewedSourceInjections(skillDirectory, policy) {
+  if (policy !== MANUAL_ONLY) return [];
+  const findings = manualOnlyPolicyFindings(skillDirectory);
+  if (findings.length > 0) throw new Error(findings.join('; '));
+  const skill = readFileSync(join(skillDirectory, 'SKILL.md'), 'utf8')
+    .replace(/^disable-model-invocation: true\n/m, '');
+  const openai = readFileSync(join(skillDirectory, 'agents', 'openai.yaml'), 'utf8')
+    .replace(/policy:\n  allow_implicit_invocation: false\n?$/, '');
+  return [
+    { relativePath: 'SKILL.md', contents: skill },
+    { relativePath: 'agents/openai.yaml', contents: openai },
+  ];
+}
+
+export function clearInvocationPolicy({ installName, policy, skillsRoot = join(homedir(), '.agents', 'skills') }) {
+  if (!SKILL_NAME.test(installName ?? '')) throw new Error(`invalid installed skill name ${JSON.stringify(installName)}`);
+  if (policy !== MANUAL_ONLY) throw new Error(`unsupported invocation policy ${JSON.stringify(policy)}`);
+  const skillDirectory = join(skillsRoot, installName);
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+  if (!existsSync(skillPath) || !existsSync(openaiPath)) throw new Error(`installed skill is incomplete: ${skillDirectory}`);
+  const skill = readFileSync(skillPath, 'utf8');
+  const openai = readFileSync(openaiPath, 'utf8');
+  const hasSkillPolicy = /^disable-model-invocation\s*:/m.test(frontmatterBounds(skill).body);
+  const hasOpenAiPolicy = /^policy\s*:\s*$/m.test(openai) || /^\s+allow_implicit_invocation\s*:/m.test(openai);
+  if (!hasSkillPolicy && !hasOpenAiPolicy) {
+    return { installName, policy: 'implicit', skillDirectory, changed: false };
+  }
+  const injected = Object.fromEntries(reviewedSourceInjections(skillDirectory, policy)
+    .map((entry) => [entry.relativePath, entry.contents]));
+  writeFileSync(skillPath, injected['SKILL.md']);
+  writeFileSync(openaiPath, injected['agents/openai.yaml']);
+  return { installName, policy: 'implicit', skillDirectory, changed: true };
+}
+
+export function applyInvocationPolicy({ installName, policy, skillsRoot = join(homedir(), '.agents', 'skills') }) {
+  if (!SKILL_NAME.test(installName ?? '')) throw new Error(`invalid installed skill name ${JSON.stringify(installName)}`);
+  if (policy !== MANUAL_ONLY) throw new Error(`unsupported invocation policy ${JSON.stringify(policy)}`);
+  const skillDirectory = join(skillsRoot, installName);
+  const skillPath = join(skillDirectory, 'SKILL.md');
+  if (!existsSync(skillPath)) throw new Error(`installed skill is missing: ${skillPath}`);
+  const openaiPath = join(skillDirectory, 'agents', 'openai.yaml');
+
+  const skillBefore = readFileSync(skillPath, 'utf8');
+  const skillAfter = manualOnlySkill(skillBefore);
+  if (skillAfter !== skillBefore) writeFileSync(skillPath, skillAfter);
+
+  mkdirSync(dirname(openaiPath), { recursive: true });
+  const openaiBefore = existsSync(openaiPath) ? readFileSync(openaiPath, 'utf8') : '';
+  const openaiAfter = manualOnlyOpenAi(openaiBefore);
+  if (openaiAfter !== openaiBefore) writeFileSync(openaiPath, openaiAfter);
+
+  const findings = manualOnlyPolicyFindings(skillDirectory);
+  if (findings.length > 0) throw new Error(findings.join('; '));
+  return { installName, policy, skillDirectory, changed: skillAfter !== skillBefore || openaiAfter !== openaiBefore };
+}
+
+function selectionEnablesTdd(env = process.env) {
+  const stateHome = env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state');
+  const path = join(stateHome, '1aboveio-skills', 'selection.json');
+  if (!existsSync(path)) return true;
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    if (state.tddImplicitInvocation === undefined) return true;
+    if (typeof state.tddImplicitInvocation !== 'boolean') {
+      throw new Error('tddImplicitInvocation must be a boolean');
+    }
+    return state.tddImplicitInvocation;
+  } catch (error) {
+    throw new Error(`cannot read TDD invocation selection at ${path}: ${error.message}`);
+  }
+}
+
+export function reconcileInvocationPolicy(options) {
+  return selectionEnablesTdd(options.env)
+    ? clearInvocationPolicy(options)
+    : applyInvocationPolicy(options);
+}
+
+function parseArgs(argv) {
+  const parsed = { installName: null, policy: null, skillsRoot: undefined, fromSelection: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--skill') parsed.installName = argv[++index];
+    else if (arg === '--policy') parsed.policy = argv[++index];
+    else if (arg === '--skills-root') parsed.skillsRoot = argv[++index];
+    else if (arg === '--from-selection') parsed.fromSelection = true;
+    else throw new Error(`unknown argument ${arg}`);
+  }
+  return parsed;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    const result = parsed.fromSelection
+      ? reconcileInvocationPolicy(parsed)
+      : applyInvocationPolicy(parsed);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`invocation-policy: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}