@1aboveio/skills 0.12.1 → 0.14.0

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

@@ -0,0 +1,172 @@
+const deepFreeze = (value) => {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+};
+
+export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
+  'e2e-test',
+  'ensure-coverage',
+  'implement-and-pr',
+  'resolve-issues',
+  'resolve-release',
+  'review-pr',
+  'smoke',
+  'engineering-runtime',
+]);
+
+export const HARNESS_RUNTIME_DEPENDENCY_MEMBERS = deepFreeze([
+  'harness-runtime',
+]);
+
+export const MATT_DEPENDENCY_MEMBERS = deepFreeze([
+  'batch-grill-me',
+  'code-review',
+  'codebase-design',
+  'diagnosing-bugs',
+  'domain-modeling',
+  'grill-me',
+  'grill-with-docs',
+  'grilling',
+  'handoff',
+  'improve-codebase-architecture',
+  'prototype',
+  'research',
+  'resolving-merge-conflicts',
+  'setup-matt-pocock-skills',
+  'tdd',
+  'to-spec',
+  'to-tickets',
+  'triage',
+  'wayfinder',
+]);
+
+// Per-invoked-skill closure, generated from SKILL.md dependencies plus cross-member
+// runtime imports. Order follows the coherence member census so the same tree always
+// produces the same identity. A generated file remains part of its owner's content
+// digest and is also named explicitly so a scoped verdict reports every identity used.
+export const WORKFLOW_TRUSTED_INVOCATION_POLICIES = deepFreeze([
+  { installName: 'tdd', policy: 'manual-only' },
+]);
+
+export const WORKFLOW_TRUSTED_DEPENDENCY_CLOSURES = deepFreeze([
+  {
+    invokedSkill: 'resolve-issues',
+    members: [
+      'tdd',
+      'harness-runtime',
+      'e2e-test',
+      'ensure-coverage',
+      'implement-and-pr',
+      'resolve-issues',
+      'review-pr',
+      'smoke',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [
+      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
+    ],
+  },
+  {
+    invokedSkill: 'resolve-release',
+    members: [
+      'harness-runtime',
+      'e2e-test',
+      'ensure-coverage',
+      'resolve-issues',
+      'resolve-release',
+      'review-pr',
+      'smoke',
+      'engineering-runtime',
+    ],
+    generatedIdentities: [
+      { member: 'resolve-issues', path: 'generated/workflow-repair-policy.json' },
+    ],
+  },
+]);
+
+// First-party content is distributed as an exact public npm release, so its identity is the package
+// and version rather than a private repository at a moving branch. The private checkout remains a
+// render target of the same manifest for local development, but it is not what an installed Workflow
+// is verified against: `revision: 'main'` is scoped to that target and never reaches coherence.
+// External sources keep their immutable reviewed revision — the migration is first-party only.
+export const WORKFLOW_TRUSTED_SOURCES = deepFreeze({
+  firstParty: {
+    id: 'first-party',
+    type: 'first-party',
+    package: '@1aboveio/skills',
+    version: '0.14.0',
+  },
+  matt: {
+    id: 'matt-pocock',
+    type: 'external',
+    repository: 'https://github.com/mattpocock/skills',
+    revision: 'ed37663cc5fbef691ddfecd080dff42f7e7e350d',
+    reviewedTree: '04b0fcb78e3de7c58744fcba2528354cc64ab988',
+  },
+});
+
+const nativeSkillsPrefix = 'npx skills@1.5.22 add';
+const nativeSkillsTarget = '--global --agent universal claude-code --skill';
+const invocationPolicyCommand = 'node "$HOME/.agents/skills/engineering-runtime/scripts/invocation-policy.mjs" --skill tdd --policy manual-only --from-selection';
+const externalArchiveLimits = 'SKILLS_DOWNLOAD_MAX_BYTES=33554432 SKILLS_EXTRACT_MAX_FILES=4096 SKILLS_EXTRACT_MAX_BYTES=67108864';
+const mattMembersArgument = MATT_DEPENDENCY_MEMBERS.join(' ');
+const firstPartyMembers = deepFreeze([
+  ...HARNESS_RUNTIME_DEPENDENCY_MEMBERS,
+  ...WORKFLOW_OWNED_MEMBERS,
+]);
+const publicPackageRelease = `${WORKFLOW_TRUSTED_SOURCES.firstParty.package}@${WORKFLOW_TRUSTED_SOURCES.firstParty.version}`;
+
+// The public package/group flow, which expands the same dependency-first recipe the steps below
+// document and delegates every write to the pinned native CLI. `--yes` is deliberately absent: repair
+// runs against an installation that is already missing, modified or mixed, which is exactly when the
+// native overwrite summary and its consent prompt are the point. The generated recipes withhold the
+// flag for the same reason, and repair guidance must not be the one place that pre-approves a
+// destructive overwrite.
+export const WORKFLOW_TRUSTED_REPAIR_RECIPE = deepFreeze({
+  id: 'engineering-workflow-dependency-first',
+  generatedFrom: 'skills/distribution/generated/recipes.json',
+  groupId: 'engineering-workflow',
+  lifecycle: 'install',
+  renderTarget: 'public-npm',
+  stopOnFailure: true,
+  steps: [
+    {
+      sourceId: 'matt-pocock',
+      sourceType: 'external',
+      repository: WORKFLOW_TRUSTED_SOURCES.matt.repository,
+      revision: WORKFLOW_TRUSTED_SOURCES.matt.revision,
+      installPath: null,
+      members: MATT_DEPENDENCY_MEMBERS,
+      invocationPolicies: WORKFLOW_TRUSTED_INVOCATION_POLICIES,
+      commands: [{
+        transport: 'https',
+        command: `${externalArchiveLimits} ${nativeSkillsPrefix} https://codeload.github.com/mattpocock/skills/tar.gz/${WORKFLOW_TRUSTED_SOURCES.matt.revision} ${nativeSkillsTarget} ${mattMembersArgument} --yes && ${invocationPolicyCommand}`,
+      }],
+      onFailure: {
+        action: 'stop',
+        message: 'Source matt-pocock fetch failed; stop this recipe before running another source.',
+      },
+    },
+    {
+      sourceId: 'first-party',
+      sourceType: 'first-party',
+      package: WORKFLOW_TRUSTED_SOURCES.firstParty.package,
+      version: WORKFLOW_TRUSTED_SOURCES.firstParty.version,
+      installPath: null,
+      members: firstPartyMembers,
+      commands: [
+        {
+          transport: 'npm',
+          command: `npx ${publicPackageRelease} install --group engineering-workflow --yes`,
+        },
+      ],
+      onFailure: {
+        action: 'stop',
+        message: 'Source first-party fetch failed; stop this recipe before running another source.',
+      },
+    },
+  ],
+});

package/skills/cicd-pipeline/mergify/references/watch-contract.md

@@ -125,6 +125,13 @@ A watcher must retain history for the PR it is watching.
 - `WAITING`: membership was observed, then one readable absence — re-read suspicion, not terminal.
 - `STALLED`: no observable queue/admission state has changed for the configured stall bound. Terminal hand-back, not a merge failure. The bound is **phase-aware**: pre-admission (never observed membership this process) uses the shorter `--admission-stall-minutes` (default 3) and reports `reason: "admission-stall"`; after membership has been observed, the full `--stall-minutes` (default 10) applies and reports `reason: "stall-bound"`. Same terminal outcome and exit code either way — only wall time and `reason` change. A dead admission path (forgotten enqueue, stale Mergify status, unreadable queue API) must not burn the post-entry bound. An `admission-stall` while Mergify is visibly waiting on a green-or-pending admission check is often a **too-short window**, not a broken enqueue — relaunch with the CI-gated 15m pair above rather than treating 60m as the next step.
 
+  Before queue membership, a completed failing non-Mergify GitHub check settles
+  immediately as `STALLED` with `reason: "admission-checks-failed"` and a
+  `failedChecks` summary. This is not `DEQUEUED`: the PR was never admitted.
+  Mergify's own queue/protection checks are excluded, pending/neutral/skipped
+  checks keep watching, and after membership Mergify remains the lifecycle
+  authority for failed batches and dequeue routing.
+
 The critical invariant: after a watcher has **observed** queue entry in this process (`everActive`), it must never keep reporting `queued:false` as a routine healthy snapshot. If the PR did not merge, loss of queue membership is a queue exit. Seeding `seenQueued` via `--seen-queued` before the first successful membership poll must not invent that observation.
 
 ## Re-read Rule

package/skills/cicd-pipeline/mergify/scripts/watch-pr-delivery-core.mjs

@@ -104,6 +104,19 @@ export function classifyObservation({
   if (mayCountLoss) {
     return { terminal: false, outcome: 'WAITING', reason: 'queue-membership-missing-reread', active, seenQueued: true, everActive: ever }
   }
+  if (Array.isArray(pr.failedChecks) && pr.failedChecks.length > 0) {
+    return {
+      terminal: true,
+      outcome: 'STALLED',
+      reason: 'admission-checks-failed',
+      detail: 'PR admission failed before active Mergify queue membership was observed.',
+      failedChecks: pr.failedChecks,
+      active,
+      seenQueued: seenQueued === true,
+      everActive: false,
+      preAdmission: true,
+    }
+  }
   // Seeded seenQueued with explicit everActive=false: still pre-admission for THIS process.
   // Keep seenQueued so phases/callers retain the resume hint, but do not start the
   // lost-membership counter until membership is observed.
@@ -136,10 +149,16 @@ export function nextPhases(phases = [], outcome) {
 
 export function observationKey({ pr = {}, queue = {} } = {}) {
   const labels = Array.isArray(pr.labels) ? [...pr.labels].sort().join(',') : ''
+  const checks = [...(pr.failedChecks || []), ...(pr.pendingChecks || [])]
+    .map((check) => `${check.name}:${check.status}`)
+    .sort()
+    .join(',')
   return JSON.stringify([
     pr.state ?? null,
     pr.mergedAt ?? null,
+    pr.headRefOid ?? null,
     labels,
+    checks,
     queue.queued ?? null,
     queue.queueState ?? queue.state ?? null,
     queue.position ?? null,
@@ -283,6 +302,28 @@ function parseJson(text) {
   try { return JSON.parse(text) } catch { return null }
 }
 
+const MERGIFY_CHECKS = new Set(['Mergify Merge Protections', 'Mergify Merge Queue'])
+const FAILED_CHECK_STATES = new Set(['ACTION_REQUIRED', 'CANCELLED', 'ERROR', 'FAILURE', 'STARTUP_FAILURE', 'TIMED_OUT'])
+const PENDING_CHECK_STATES = new Set(['EXPECTED', 'IN_PROGRESS', 'PENDING', 'QUEUED', 'REQUESTED', 'WAITING'])
+
+export function summarizeStatusChecks(rollup) {
+  const failedChecks = []
+  const pendingChecks = []
+  for (const check of Array.isArray(rollup) ? rollup : []) {
+    const name = check?.name || check?.context || 'unnamed-check'
+    if (MERGIFY_CHECKS.has(name)) continue
+    const status = String(check?.conclusion || check?.state || check?.status || 'UNKNOWN').toUpperCase()
+    const summary = {
+      name,
+      status,
+      detailsUrl: check?.detailsUrl || check?.targetUrl || null,
+    }
+    if (FAILED_CHECK_STATES.has(status)) failedChecks.push(summary)
+    else if (PENDING_CHECK_STATES.has(status)) pendingChecks.push(summary)
+  }
+  return { failedChecks, pendingChecks }
+}
+
 // Issue #629: the one piece of history a single `labels` snapshot cannot carry — WHEN a
 // `dequeued` label was applied. `gh pr view --json` has no `timelineItems` field in the CLI
 // version this was built against (`gh pr view --json timelineItems` errors "Unknown JSON
@@ -380,18 +421,21 @@ function prObservation({ repo, pr, intervalSeconds, stallMinutes, admissionStall
   // `comments` costs nothing extra to request in this same call and carries the one signal
   // `dequeuedAtFromComments` needs — no additional subprocess read, so the READS_PER_POLL
   // budget below is unaffected by issue #629's fix.
-  const result = run('gh', ['pr', 'view', String(pr), '--repo', repo, '--json', 'state,mergedAt,mergeCommit,labels,url,comments'], { timeout: readTimeoutForArgs({ intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) })
+  const result = run('gh', ['pr', 'view', String(pr), '--repo', repo, '--json', 'state,mergedAt,mergeCommit,headRefOid,labels,url,comments,statusCheckRollup'], { timeout: readTimeoutForArgs({ intervalSeconds, stallMinutes, admissionStallMinutes, maxMinutes, everActive }) })
   if (!result.ok) return { readable: false, error: result.stderr || result.stdout }
   const data = parseJson(result.stdout)
   if (!data) return { readable: false, error: 'gh pr view returned invalid JSON' }
+  const checks = summarizeStatusChecks(data.statusCheckRollup)
   return {
     readable: true,
     state: data.state || null,
     mergedAt: data.mergedAt || null,
     mergeCommitOid: data.mergeCommit?.oid || null,
+    headRefOid: data.headRefOid || null,
     labels: (data.labels || []).map((label) => label.name).filter(Boolean),
     url: data.url || null,
     dequeuedAtMs: dequeuedAtFromComments(data.comments),
+    ...checks,
   }
 }
 
@@ -501,6 +545,8 @@ The script observes only; it never queues, dequeues, merges, or records state.
 
 Enqueue first. On a repo with manual delivery (no auto_merge_conditions, autoqueue: false)
 an unqueued PR never enters the queue on its own, so this watch can only ever end STALLED.
+Before admission, a completed failing non-Mergify GitHub check ends the watch as STALLED
+with reason admission-checks-failed; after admission, Mergify owns failure/dequeue routing.
 
 Options:
   --interval-seconds <n>         Poll interval, default 90
@@ -595,6 +641,7 @@ export async function runCli(argv) {
     })
     if (verdict.everActive === true) everActive = true
     if (verdict.seenQueued === true) seenQueued = true
+    if (verdict.preAdmission === true) phases = nextPhases(phases, 'NOT_YET_QUEUED')
     phases = nextPhases(phases, verdict.outcome)
     const payload = {
       outcome: verdict.outcome,
@@ -605,10 +652,21 @@ export async function runCli(argv) {
       seenQueued,
       everActive,
       phases,
+      failedChecks: verdict.failedChecks || pr.failedChecks || [],
       missingActiveReads,
       observations,
       elapsedMs: Date.now() - startedMs,
-      pr: { state: pr.state || null, mergedAt: pr.mergedAt || null, labels: pr.labels || [], url: pr.url || null, readable: pr.readable !== false, dequeuedAtMs: pr.dequeuedAtMs ?? null },
+      pr: {
+        state: pr.state || null,
+        mergedAt: pr.mergedAt || null,
+        headRefOid: pr.headRefOid || null,
+        labels: pr.labels || [],
+        url: pr.url || null,
+        readable: pr.readable !== false,
+        dequeuedAtMs: pr.dequeuedAtMs ?? null,
+        failedChecks: pr.failedChecks || [],
+        pendingChecks: pr.pendingChecks || [],
+      },
       queue: { queued: queue.queued === true, queueState: queue.queueState || null, position: queue.position ?? null, readable: queue.readable !== false },
     }
 

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -294,7 +294,8 @@
         "reviewedTree": "04b0fcb78e3de7c58744fcba2528354cc64ab988"
       },
       "contentDigest": "81eca2a5b53a63f481c0849be7a663a8cd43d5cf53f32b644ec0a2f50cf91aa2",
-      "digestExcludes": []
+      "digestExcludes": [],
+      "invocationPolicy": "manual-only"
     },
     {
       "installName": "to-spec",
@@ -360,7 +361,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "eff6c7b5931bce5b2265a619bccddd371a89df6ce7bc2edc74f11d00060a71dd",
       "digestExcludes": []
@@ -373,7 +374,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "08230dc57a53d6526692b50138038abbd80abce1a067e01c52ad6acc182caf7e",
       "digestExcludes": []
@@ -386,7 +387,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "9eea7bfba348ddaea1b934c9a7fabdd9b101df8a146e1c93e947da4d335f1d98",
       "digestExcludes": []
@@ -399,7 +400,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "58b0556228a9271cf9e33727a05fc08a4fdfd29512ec0936b169f0a55d60e6ef",
       "digestExcludes": []
@@ -412,9 +413,9 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
-      "contentDigest": "c8e731b2441e03b2a7d2999f9888427f842f41b16f40c43d4d0965faad2eb925",
+      "contentDigest": "9eac84bee618e57564eb702d198484b6e78f8d27e3db621d087f0dd2dc048b58",
       "digestExcludes": []
     },
     {
@@ -425,7 +426,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "b5af4dccf703362d4f41cac4fdff48305f652a00338d85975a2e5c35ec6bc61c",
       "digestExcludes": []
@@ -438,7 +439,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "f048fd00c69f2dc666fc7a3096cfeee6dfba73933bfb69602f3f0e26159798cc",
       "digestExcludes": []
@@ -451,7 +452,7 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
       "contentDigest": "90a7c4e1ad6da1e632ea2c5259e4967ffebb84353adccbca8dfc5d6bc50b60c1",
       "digestExcludes": []
@@ -464,15 +465,15 @@
         "id": "first-party",
         "type": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1"
+        "version": "0.14.0"
       },
-      "contentDigest": "d53c76bf1d2118c59b443c5757d7d4c3bcf489fd8e345b68b44127de9a085e5b",
+      "contentDigest": "0d71ce70f3180bba021005e056f028ef5a2018eb187078ab8c691a5a000a924e",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "785896ddc88471f058dcd79a651bb2558630706c874e4222562cc828df6aae91",
+  "releaseIdentity": "5c171520b6818f86f6b88cd60e5e4e0168dd6f89256690925c02758105c6c8a5",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -509,10 +510,16 @@
           "triage",
           "wayfinder"
         ],
+        "invocationPolicies": [
+          {
+            "installName": "tdd",
+            "policy": "manual-only"
+          }
+        ],
         "commands": [
           {
             "transport": "https",
-            "command": "SKILLS_DOWNLOAD_MAX_BYTES=33554432 SKILLS_EXTRACT_MAX_FILES=4096 SKILLS_EXTRACT_MAX_BYTES=67108864 npx skills@1.5.22 add https://codeload.github.com/mattpocock/skills/tar.gz/ed37663cc5fbef691ddfecd080dff42f7e7e350d --global --agent universal claude-code --skill batch-grill-me code-review codebase-design diagnosing-bugs domain-modeling grill-me grill-with-docs grilling handoff improve-codebase-architecture prototype research resolving-merge-conflicts setup-matt-pocock-skills tdd to-spec to-tickets triage wayfinder"
+            "command": "SKILLS_DOWNLOAD_MAX_BYTES=33554432 SKILLS_EXTRACT_MAX_FILES=4096 SKILLS_EXTRACT_MAX_BYTES=67108864 npx skills@1.5.22 add https://codeload.github.com/mattpocock/skills/tar.gz/ed37663cc5fbef691ddfecd080dff42f7e7e350d --global --agent universal claude-code --skill batch-grill-me code-review codebase-design diagnosing-bugs domain-modeling grill-me grill-with-docs grilling handoff improve-codebase-architecture prototype research resolving-merge-conflicts setup-matt-pocock-skills tdd to-spec to-tickets triage wayfinder --yes && node \"$HOME/.agents/skills/engineering-runtime/scripts/invocation-policy.mjs\" --skill tdd --policy manual-only --from-selection"
           }
         ],
         "onFailure": {
@@ -524,7 +531,7 @@
         "sourceId": "first-party",
         "sourceType": "first-party",
         "package": "@1aboveio/skills",
-        "version": "0.12.1",
+        "version": "0.14.0",
         "installPath": null,
         "members": [
           "harness-runtime",
@@ -540,7 +547,7 @@
         "commands": [
           {
             "transport": "npm",
-            "command": "npx @1aboveio/skills@0.12.1 install --group engineering-workflow"
+            "command": "npx @1aboveio/skills@0.14.0 install --group engineering-workflow --yes"
           }
         ],
         "onFailure": {

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;
+  }
+}