github-delivery-os 1.2.0 → 1.2.1

package/.github/scripts/authorize-deployment-verdict.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// Pure verdict-computation logic for authorize-deployment.yml, extracted out
+// of the inline actions/github-script step so it can be unit tested directly
+// (see test/authorize-deployment-verdict.test.js) instead of only verified
+// by hand whenever it changes. Has no dependency on the `github`/`context`
+// globals actions/github-script injects — everything it needs is passed in.
+
+// Anchored to comment start + word boundary so keywords must lead the
+// comment (matches the documented convention) and can't match inside a
+// larger word (e.g. "ok" no longer matches "okay", "reject" no longer
+// matches "rejection") or as a substring anywhere in unrelated prose.
+const DECLINE_RE = /^(declined|rejected|reject|not approved)\b/i;
+const APPROVE_RE = /^(approved|approve|ok|go ahead)\b/i;
+const QA_APPROVE_RE = /^(qa approved|approved|qa ok|looks good)\b/i;
+
+const normalize = (s) => (s || '').toLowerCase();
+
+/**
+ * Walks comments in chronological order and keeps the LATEST verdict from
+ * each approver, rather than stopping at the first decline seen. This lets a
+ * release approver re-approve after an earlier decline (e.g. once fixes
+ * land) instead of being permanently stuck as declined.
+ *
+ * @param {Array<{ user?: { login?: string | null } | null, body?: string | null }>} comments
+ *   Chronological (oldest first), matching the order github.paginate(listComments) returns.
+ * @param {string} releaseApprover
+ * @param {string} qaApprover
+ * @returns {{ releaseVerdict: 'approved' | 'declined' | null, qaApproved: boolean }}
+ */
+function computeVerdict(comments, releaseApprover, qaApprover) {
+  let releaseVerdict = null;
+  let qaApproved = false;
+
+  for (const comment of comments) {
+    const login = comment.user && comment.user.login;
+    const body = (comment.body || '').trim();
+
+    if (normalize(login) === normalize(releaseApprover)) {
+      if (DECLINE_RE.test(body)) {
+        releaseVerdict = 'declined';
+      } else if (APPROVE_RE.test(body)) {
+        releaseVerdict = 'approved';
+      }
+    }
+
+    if (normalize(login) === normalize(qaApprover) && QA_APPROVE_RE.test(body)) {
+      qaApproved = true;
+    }
+  }
+
+  return { releaseVerdict, qaApproved };
+}
+
+module.exports = { computeVerdict, DECLINE_RE, APPROVE_RE, QA_APPROVE_RE };

package/.github/scripts/auto-close-sprint.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Pure burn-down/health computation for auto-close-sprint.yml, extracted so
+// it can be unit tested directly (see test/auto-close-sprint.test.js)
+// instead of only verified by hand.
+
+/**
+ * @param {string} body - a child issue's body
+ * @returns {number | null} the parent sprint issue number, or null if this
+ *   issue isn't a sprint child (no "Parent Sprint: #N" line).
+ */
+function parseParentSprintNumber(body) {
+  const match = (body || '').match(/Parent Sprint:\s*#(\d+)/);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Parses sprint dates out of a sprint issue's body, supporting both the
+ * combined "Sprint Dates: X to Y" format and the separate "Sprint Start" /
+ * "Sprint End" field format (the sprint_planning.yml template).
+ *
+ * @param {string} sprintBody - the sprint (parent) issue's body
+ * @returns {{ startDate: Date, endDate: Date } | null} null if neither
+ *   format matched.
+ */
+function parseSprintDates(sprintBody) {
+  const body = sprintBody || '';
+
+  const rangeMatch = body.match(/Sprint Dates[\s\S]*?(\d{4}-\d{2}-\d{2})\s*to\s*(\d{4}-\d{2}-\d{2})/i);
+  if (rangeMatch) {
+    return { startDate: new Date(rangeMatch[1]), endDate: new Date(rangeMatch[2]) };
+  }
+
+  const startMatch = body.match(/Sprint Start[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
+  const endMatch = body.match(/Sprint End[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
+  if (startMatch && endMatch) {
+    return { startDate: new Date(startMatch[1]), endDate: new Date(endMatch[1]) };
+  }
+
+  return null;
+}
+
+/**
+ * @param {Date} startDate
+ * @param {Date} endDate
+ * @param {Date} now
+ * @returns {number} percent of the sprint's duration elapsed as of `now`,
+ *   clamped to [0, 100]. Returns 100 for a zero-or-negative-length sprint
+ *   (Start >= End — a data-entry mistake) or an unparseable date (e.g. an
+ *   out-of-range "2026-13-05" typo, which regex-matches the YYYY-MM-DD
+ *   shape but produces an Invalid Date) instead of dividing by zero or NaN:
+ *   that NaN would otherwise flow into the posted burn-down as "Time
+ *   Elapsed: NaN%", and every NaN comparison in computeHealthEmoji is
+ *   false, so it'd silently default to the green/no-warning branch instead
+ *   of flagging the broken dates. `!(totalDuration > 0)` (rather than
+ *   `totalDuration <= 0`) catches NaN too, since every comparison against
+ *   NaN is false — `NaN <= 0` is false, but so is `NaN > 0`, and negating
+ *   that is true.
+ */
+function computeTimePercent(startDate, endDate, now) {
+  const totalDuration = endDate - startDate;
+  if (!(totalDuration > 0)) return 100;
+  const elapsed = now - startDate;
+  return Math.max(0, Math.min(100, Math.round((elapsed / totalDuration) * 100)));
+}
+
+/**
+ * @param {Array<{ state: string }>} children
+ * @returns {{ progressPercent: number, closedCount: number, totalCount: number }}
+ */
+function computeProgress(children) {
+  const totalCount = children.length;
+  const closedCount = children.filter((i) => i.state === 'closed').length;
+  const progressPercent = totalCount === 0 ? 0 : Math.round((closedCount / totalCount) * 100);
+  return { progressPercent, closedCount, totalCount };
+}
+
+/**
+ * Sprint health relative to time elapsed: red if progress trails time by
+ * more than 10 points, yellow if behind at all, green otherwise.
+ *
+ * @returns {'🟢' | '🟡' | '🔴'}
+ */
+function computeHealthEmoji(progressPercent, timePercent) {
+  if (progressPercent < timePercent - 10) return '🔴';
+  if (progressPercent < timePercent) return '🟡';
+  return '🟢';
+}
+
+/**
+ * @returns {string} a block-character progress bar, e.g. "████░░░░░░░░░░░░░░░░".
+ */
+function renderBurnDown(progressPercent, totalBars = 20) {
+  const filledBars = Math.round((progressPercent / 100) * totalBars);
+  return '█'.repeat(filledBars) + '░'.repeat(totalBars - filledBars);
+}
+
+/**
+ * Replaces any previous "## 🚦 Sprint Status" block in the sprint body with
+ * a freshly rendered one (appended at the end).
+ */
+function updateSprintBody(sprintBody, { progressPercent, timePercent, healthEmoji, burnDown }) {
+  let updatedBody = (sprintBody || '').replace(/## 🚦 Sprint Status[\s\S]*?---/g, '');
+
+  updatedBody +=
+    `\n\n---\n\n## 🚦 Sprint Status\n\n` +
+    `Progress: **${progressPercent}%**\n` +
+    `Time Elapsed: **${timePercent}%**\n\n` +
+    `Health: ${healthEmoji}\n\n` +
+    `### 📉 Burn-down\n` +
+    `\`${burnDown}\` ${progressPercent}%\n\n---`;
+
+  return updatedBody;
+}
+
+module.exports = {
+  parseParentSprintNumber,
+  parseSprintDates,
+  computeTimePercent,
+  computeProgress,
+  computeHealthEmoji,
+  renderBurnDown,
+  updateSprintBody,
+};

package/.github/scripts/sprint-child-creator.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Pure parsing logic for sprint-child-creator.yml, extracted so it can be
+// unit tested directly (see test/sprint-child-creator.test.js) instead of
+// only verified by hand.
+
+/**
+ * Extracts the feature list from a sprint-planning issue body's
+ * "### Sprint Features" section (one feature per line, up to the next
+ * heading or end of body).
+ *
+ * @param {string} body - the sprint issue's body
+ * @returns {string[]} feature titles, in the order they appear. Empty if
+ *   there's no Sprint Features section, or it has no non-blank lines.
+ */
+function parseFeatures(body) {
+  const featuresMatch = (body || '').match(/### Sprint Features[\s\S]*?(?=###|$)/);
+  if (!featuresMatch) return [];
+
+  return featuresMatch[0]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('###'));
+}
+
+/**
+ * @param {number} parentNumber - the sprint (parent) issue number
+ * @returns {string} body to use for each generated child issue
+ */
+function buildChildBody(parentNumber) {
+  return `Parent Sprint: #${parentNumber}\n\n---\n*Created by Delivery OS Sprint Child Creator*`;
+}
+
+module.exports = { parseFeatures, buildChildBody };

package/.github/workflows/authorize-deployment.yml

@@ -58,19 +58,40 @@ jobs:
 
             const { releaseVerdict, qaApproved } = computeVerdict(comments, releaseApprover, qaApprover);
 
-            const currentLabels = (context.payload.issue.labels || []).map((l) => l.name);
+            // Nothing to act on this run (most comments on a production issue
+            // are routine discussion, not a verdict-changing approval/decline)
+            // — return before the live label fetch below, which only matters
+            // once we actually have a verdict to check against current state.
+            const hasActionableVerdict =
+              releaseVerdict === "declined" || (releaseVerdict === "approved" && qaApproved);
+            if (!hasActionableVerdict) return;
+
+            // Fetch labels live rather than trusting context.payload.issue.labels:
+            // that's a snapshot fixed at the triggering event's delivery time.
+            // Two comments posted seconds apart queue under the concurrency
+            // group above and run sequentially, but each was still delivered
+            // (and its label snapshot captured) before either job actually ran
+            // — serializing execution order doesn't refresh an already-stale
+            // snapshot. A live re-fetch is what actually lets the second
+            // (queued) run see what the first one just did.
+            const { data: liveIssue } = await github.rest.issues.get({ owner, repo, issue_number: issueNumber });
+            const currentLabels = (liveIssue.labels || []).map((l) => (typeof l === "string" ? l : l.name));
             const alreadyDeclined = currentLabels.includes("declined");
             const alreadyReady = currentLabels.includes("ready-for-deploy");
 
             if (releaseVerdict === "declined") {
               if (alreadyDeclined) return; // avoid re-posting on every later comment
 
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: issueNumber,
-                labels: ["declined"]
-              });
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: issueNumber,
+                  labels: ["declined"]
+                });
+              } catch (e) {
+                console.log(`Failed to add 'declined' label: ${e.message || e}`);
+              }
 
               try {
                 await github.rest.issues.removeLabel({
@@ -103,12 +124,16 @@ jobs:
                 });
               } catch (e) {}
 
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number: issueNumber,
-                labels: ["ready-for-deploy"]
-              });
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: issueNumber,
+                  labels: ["ready-for-deploy"]
+                });
+              } catch (e) {
+                console.log(`Failed to add 'ready-for-deploy' label: ${e.message || e}`);
+              }
 
               await github.rest.issues.createComment({
                 owner,

package/.github/workflows/auto-close-sprint.yml

@@ -70,17 +70,23 @@ jobs:
 
             // Paginate: a plain listForRepo call caps at one page (100 issues) and
             // would silently undercount children in repos with more open+closed
-            // issues than that, skewing the burn-down. Scoped to `sprint-active`
-            // (the label every child issue gets on creation) instead of every
-            // issue in the repo, so this stays cheap in repos with a lot of
-            // unrelated issue history — this workflow now runs serialized per
-            // repo, so an unscoped full-repo fetch on every child close would
-            // add up fast.
+            // issues than that, skewing the burn-down.
+            //
+            // Deliberately NOT scoped to labels: "sprint-active" (an earlier
+            // version of this workflow did that, for cost — cheaper in repos
+            // with a lot of unrelated issue history). That's wrong: a child
+            // issue relabeled away from sprint-active during triage (e.g. to
+            // "bug") while still open would silently drop out of BOTH the
+            // numerator and denominator of the progress calculation instead
+            // of just being excluded from the closed count — the sprint could
+            // report inflated progress, or even reach a false 100% and
+            // auto-close, while that untracked child is still open. Matches
+            // docs/governance.md's documented trigger ("body has Parent
+            // Sprint"), which is body-content-based, not label-based.
             const allIssues = await github.paginate(github.rest.issues.listForRepo, {
               owner: context.repo.owner,
               repo: context.repo.repo,
               state: "all",
-              labels: "sprint-active",
               per_page: 100
             });
 

package/.github/workflows/telegram-issues.yml

@@ -103,14 +103,20 @@ jobs:
             # Case-insensitive actor comparison: GitHub logins are case-insensitive,
             # but a plain bash == is not, so a RELEASE_APPROVER var with different
             # casing than the actual login would otherwise never match here.
-            # Anchored to the start of a line, matching the same keyword set and
-            # convention as authorize-deployment.yml's DECLINE_RE, so this alert
-            # can't fire for a comment that workflow wouldn't actually treat as a
-            # decline (e.g. "not approved" appearing mid-sentence).
-            if [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(declined|rejected|reject|not approved)"; then
+            # Anchored to the start of a line + word boundary (\b), matching the
+            # same keyword set and convention as authorize-deployment.yml's real
+            # DECLINE_RE/APPROVE_RE, so this alert can't fire for a comment that
+            # workflow wouldn't actually treat as a decline/approval (e.g. "not
+            # approved" mid-sentence, or "okay, I'll look at this tomorrow" —
+            # "ok" without \b would otherwise match as a false approval).
+            if [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(declined|rejected|reject|not approved)\b"; then
               MESSAGE="🔴🛑 RELEASE DECLINED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
+            # Matches authorize-deployment.yml's full APPROVE_RE keyword set
+            # (approved|approve|ok|go ahead), not just "approved" — it used to
+            # miss "ok"/"go ahead"/"approve", so a release could be approved
+            # for real with no Telegram alert sent for it.
+            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iqE "^(approved|approve|ok|go ahead)\b"; then
               MESSAGE="🟢🛡️ RELEASE APPROVED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
             elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'bug') }}" == "true" ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {
@@ -45,6 +45,9 @@
     ".github/workflows/auto-assign-qa.yml",
     ".github/workflows/telegram-issues.yml",
     ".github/workflows/setup-labels.yml",
+    ".github/scripts/authorize-deployment-verdict.js",
+    ".github/scripts/auto-close-sprint.js",
+    ".github/scripts/sprint-child-creator.js",
     ".github/ISSUE_TEMPLATE",
     ".claude/skills/delivery-ops"
   ],

package/src/install.js

@@ -20,6 +20,22 @@ const WORKFLOWS = [
   'setup-labels',
 ];
 
+// Pure logic some of the workflows above require() at runtime from
+// .github/scripts/<name>.js (see .github/workflows/authorize-deployment.yml
+// etc.) — these are required dependencies of those workflows, not optional,
+// so they're always copied alongside them, the same as WORKFLOWS. Also list
+// them explicitly in package.json's "files".
+const SCRIPTS = ['authorize-deployment-verdict', 'auto-close-sprint', 'sprint-child-creator'];
+
+// Which workflow requires which script, so `status` can flag a workflow
+// that's present but whose required script is missing (an install that will
+// fail with MODULE_NOT_FOUND the next time that workflow actually runs).
+const REQUIRED_SCRIPT_BY_WORKFLOW = {
+  'authorize-deployment': 'authorize-deployment-verdict',
+  'auto-close-sprint': 'auto-close-sprint',
+  'sprint-child-creator': 'sprint-child-creator',
+};
+
 const LABELS = [
   ['intake', '0E8A16'],
   ['bug', 'D93F0B'],
@@ -101,6 +117,44 @@ function fetchLatestVersion(timeoutMs = 3000) {
   });
 }
 
+// Copies each `${name}${ext}` from srcDir to destDir for a fixed list of
+// expected filenames — the shared logic behind copying WORKFLOWS and SCRIPTS
+// (both: a required, always-on set of individually-named files, as opposed
+// to templates, which copies whatever's found in a directory, or the skill,
+// a single optional file). `label` is what's printed for each entry, e.g.
+// `.github/scripts/auto-close-sprint.js` — pass names already including
+// their directory prefix so log lines are self-explanatory on their own.
+function copyManagedFiles(names, ext, srcDir, destDir, { overwrite, dryRun, relDir }) {
+  let copied = 0;
+  let skipped = 0;
+
+  for (const name of names) {
+    const src = path.join(srcDir, `${name}${ext}`);
+    const dest = path.join(destDir, `${name}${ext}`);
+    const label = `${relDir}/${name}${ext}`;
+
+    if (!fs.existsSync(src)) {
+      console.log(`  Warning: source not found: ${label}`);
+      skipped++; // missing source must block a "clean install" claim, not just warn
+      continue;
+    }
+
+    if (fs.existsSync(dest) && !overwrite) {
+      console.log(`  Skipped (exists): ${label}`);
+      skipped++;
+    } else if (dryRun) {
+      console.log(`  [dry-run] Would create: ${label}`);
+      copied++;
+    } else {
+      fs.copyFileSync(src, dest);
+      console.log(`  Created: ${label}`);
+      copied++;
+    }
+  }
+
+  return { copied, skipped };
+}
+
 function getPackageRoot() {
   // When installed via npm, __dirname is node_modules/github-delivery-os/src
   const possibleRoots = [
@@ -129,6 +183,7 @@ function runInstall(options) {
   const pkgRoot = getPackageRoot();
   const workflowsSrc = path.join(pkgRoot, '.github', 'workflows');
   const templatesSrc = path.join(pkgRoot, '.github', 'ISSUE_TEMPLATE');
+  const scriptsSrc = path.join(pkgRoot, '.github', 'scripts');
   const skillSrc = path.join(pkgRoot, SKILL_REL_PATH);
   const targetAbs = path.resolve(process.cwd(), targetDir);
 
@@ -151,41 +206,42 @@ function runInstall(options) {
   // Ensure target structure
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
+  const scriptsDest = path.join(targetAbs, '.github', 'scripts');
 
   if (!dryRun) {
     fs.mkdirSync(workflowsDest, { recursive: true });
     fs.mkdirSync(templatesDest, { recursive: true });
+    fs.mkdirSync(scriptsDest, { recursive: true });
   }
 
   let workflowsCopied = 0;
   let templatesCopied = 0;
+  let scriptsCopied = 0;
   let skillCopied = 0;
-  let workflowsSkipped = 0;
-  let templatesSkipped = 0;
-  let skillSkipped = 0;
+  let workflowsSkipped;
+  let scriptsSkipped;
 
-  // Copy workflows
-  for (const wf of WORKFLOWS) {
-    const src = path.join(workflowsSrc, `${wf}.yml`);
-    const dest = path.join(workflowsDest, `${wf}.yml`);
-
-    if (!fs.existsSync(src)) {
-      console.log(`  Warning: source not found: ${wf}.yml`);
-      continue;
-    }
+  // Copy workflows (always on — not optional)
+  ({ copied: workflowsCopied, skipped: workflowsSkipped } = copyManagedFiles(
+    WORKFLOWS,
+    '.yml',
+    workflowsSrc,
+    workflowsDest,
+    { overwrite, dryRun, relDir: '.github/workflows' }
+  ));
+
+  // Copy the scripts the workflows above require() at runtime — required,
+  // not optional, so (unlike templates/skill) this always runs too.
+  ({ copied: scriptsCopied, skipped: scriptsSkipped } = copyManagedFiles(
+    SCRIPTS,
+    '.js',
+    scriptsSrc,
+    scriptsDest,
+    { overwrite, dryRun, relDir: '.github/scripts' }
+  ));
 
-    if (fs.existsSync(dest) && !overwrite) {
-      console.log(`  Skipped (exists): ${wf}.yml`);
-      workflowsSkipped++;
-    } else if (dryRun) {
-      console.log(`  [dry-run] Would create: ${wf}.yml`);
-      workflowsCopied++;
-    } else {
-      fs.copyFileSync(src, dest);
-      console.log(`  Created: ${wf}.yml`);
-      workflowsCopied++;
-    }
-  }
+  let templatesSkipped = 0;
+  let skillSkipped = 0;
 
   // Copy templates
   if (withTemplates && fs.existsSync(templatesSrc)) {
@@ -291,12 +347,28 @@ function runInstall(options) {
   }
 
   // Record what got installed so `status` can report a version and detect
-  // drift. Only claim a version when the on-disk files actually match it: an
-  // overwrite, or a fresh install where nothing had to be skipped. A partial
-  // skip-mode install would leave older file content on disk, so don't
-  // overwrite a previously recorded (possibly accurate, possibly newer)
-  // version with a number that isn't actually true on disk yet.
-  const cleanInstall = overwrite || (workflowsSkipped === 0 && templatesSkipped === 0 && skillSkipped === 0);
+  // drift. Only claim a version when the on-disk files actually match it.
+  //
+  // Two ways this can go wrong, both of which must block the claim:
+  //  1. A skip-mode install left older content on disk for something that
+  //     WAS requested this run (tracked by the *Skipped counters below).
+  //  2. An --overwrite run touches only what was explicitly requested
+  //     (workflows + scripts always; templates/skill only if their flags
+  //     were passed) — templates or skill already on disk from an earlier
+  //     install, but not requested this run, are left untouched and stale,
+  //     even though --overwrite makes every *Skipped counter read 0. Naively
+  //     trusting `overwrite` alone would then claim the whole install is
+  //     current when part of it demonstrably wasn't touched.
+  const templatesPresentButNotTouched =
+    !withTemplates && TEMPLATES.some((t) => fs.existsSync(path.join(templatesDest, t)));
+  const skillPresentButNotTouched = !withSkill && fs.existsSync(skillPath(targetAbs));
+  const cleanInstall =
+    workflowsSkipped === 0 &&
+    templatesSkipped === 0 &&
+    scriptsSkipped === 0 &&
+    skillSkipped === 0 &&
+    !templatesPresentButNotTouched &&
+    !skillPresentButNotTouched;
   if (!dryRun && cleanInstall) {
     const pkgVersion = require(path.join(pkgRoot, 'package.json')).version;
     writeManifest(targetAbs, pkgVersion);
@@ -305,19 +377,28 @@ function runInstall(options) {
   // Summary
   console.log('');
   if (!dryRun && !cleanInstall) {
-    console.log('  Note: some files already existed and were skipped, so the recorded');
-    console.log('  Delivery OS version was not updated. Re-run with --overwrite to sync');
-    console.log('  all files (and the recorded version) to the latest release.');
+    if (templatesPresentButNotTouched || skillPresentButNotTouched) {
+      console.log('  Note: previously-installed templates and/or the Claude Code skill exist');
+      console.log('  on disk but were not requested this run, so the recorded Delivery OS');
+      console.log('  version was not updated. Re-run with --overwrite plus --with-templates');
+      console.log('  and/or --with-skill to bring everything (and the recorded version) in sync.');
+    } else {
+      console.log('  Note: some files already existed and were skipped, so the recorded');
+      console.log('  Delivery OS version was not updated. Re-run with --overwrite to sync');
+      console.log('  all files (and the recorded version) to the latest release.');
+    }
     console.log('');
   }
-  if (workflowsCopied > 0 || templatesCopied > 0 || skillCopied > 0 || labelsCreated > 0) {
+  if (workflowsCopied > 0 || templatesCopied > 0 || scriptsCopied > 0 || skillCopied > 0 || labelsCreated > 0) {
     if (dryRun) {
       if (workflowsCopied > 0) console.log(`Would install ${workflowsCopied} workflow(s).`);
       if (templatesCopied > 0) console.log(`Would copy ${templatesCopied} issue template(s).`);
+      if (scriptsCopied > 0) console.log(`Would install ${scriptsCopied} supporting script(s).`);
       if (skillCopied > 0) console.log('Would add the Claude Code delivery-ops skill.');
     } else {
       if (workflowsCopied > 0) console.log(`Installed ${workflowsCopied} workflow(s).`);
       if (templatesCopied > 0) console.log(`Copied ${templatesCopied} issue template(s).`);
+      if (scriptsCopied > 0) console.log(`Installed ${scriptsCopied} supporting script(s).`);
       if (skillCopied > 0) console.log('Added the Claude Code delivery-ops skill.');
       if (labelsCreated > 0) console.log(`Created ${labelsCreated} label(s).`);
     }
@@ -380,7 +461,18 @@ async function runStatus(options) {
   );
   const skillInstalled = fs.existsSync(skillPath(targetAbs));
 
-  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+  // A workflow can be present while the script it require()s at runtime is
+  // not — e.g. an install from before this check existed, or a manual
+  // partial copy. That workflow will fail (MODULE_NOT_FOUND) the next time
+  // it actually runs, silently, since nothing here executes the workflow
+  // itself to notice.
+  const brokenWorkflows = installedWorkflows.filter((wf) => {
+    const requiredScript = REQUIRED_SCRIPT_BY_WORKFLOW[wf];
+    if (!requiredScript) return false;
+    return !fs.existsSync(path.join(targetAbs, '.github', 'scripts', `${requiredScript}.js`));
+  });
+
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0 || skillInstalled) {
     const manifest = readManifest(targetAbs);
     if (manifest && manifest.version) {
       const installedOn = manifest.installedAt ? ` (installed ${manifest.installedAt.slice(0, 10)})` : '';
@@ -411,6 +503,17 @@ async function runStatus(options) {
     installedWorkflows.forEach((wf) => console.log(`  ✓ ${wf}.yml`));
     console.log('');
   }
+
+  if (brokenWorkflows.length > 0) {
+    console.log('⚠️  Broken install detected:');
+    brokenWorkflows.forEach((wf) => {
+      console.log(`  ${wf}.yml requires .github/scripts/${REQUIRED_SCRIPT_BY_WORKFLOW[wf]}.js, which is missing.`);
+    });
+    console.log('  That workflow will fail with MODULE_NOT_FOUND the next time it runs.');
+    console.log('  Fix: npx github-delivery-os@latest install --overwrite .');
+    console.log('');
+  }
+
   if (installedTemplates.length > 0) {
     console.log('Templates:');
     installedTemplates.forEach((t) => console.log(`  ✓ ${t}`));
@@ -424,7 +527,7 @@ async function runStatus(options) {
     console.log('');
   }
 
-  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0 || skillInstalled) {
     console.log('Claude Code skill:');
     console.log(
       skillInstalled
@@ -434,7 +537,7 @@ async function runStatus(options) {
     console.log('');
   }
 
-  if (installedWorkflows.length === 0 && installedTemplates.length === 0) {
+  if (installedWorkflows.length === 0 && installedTemplates.length === 0 && !skillInstalled) {
     console.log('Delivery OS is not installed in this repository.');
     console.log('Run: npx github-delivery-os install --with-templates .');
   } else {
@@ -450,6 +553,7 @@ function runUninstall(options) {
   const targetAbs = path.resolve(process.cwd(), targetDir);
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
+  const scriptsDest = path.join(targetAbs, '.github', 'scripts');
 
   console.log('=== GitHub Delivery Operating System — Uninstall ===');
   console.log(`Target: ${targetAbs}`);
@@ -458,6 +562,7 @@ function runUninstall(options) {
 
   let workflowsRemoved = 0;
   let templatesRemoved = 0;
+  let scriptsRemoved = 0;
 
   for (const wf of WORKFLOWS) {
     const dest = path.join(workflowsDest, `${wf}.yml`);
@@ -472,6 +577,21 @@ function runUninstall(options) {
     }
   }
 
+  // Scripts are a required dependency of the workflows above, not optional,
+  // so (like workflows) they're always removed, not gated behind a flag.
+  for (const name of SCRIPTS) {
+    const dest = path.join(scriptsDest, `${name}.js`);
+    if (fs.existsSync(dest)) {
+      if (dryRun) {
+        console.log(`  [dry-run] Would remove: .github/scripts/${name}.js`);
+      } else {
+        fs.unlinkSync(dest);
+        console.log(`  Removed: .github/scripts/${name}.js`);
+      }
+      scriptsRemoved++;
+    }
+  }
+
   if (withTemplates) {
     for (const t of TEMPLATES) {
       const dest = path.join(templatesDest, t);
@@ -501,11 +621,25 @@ function runUninstall(options) {
     }
   }
 
-  // Remove the version manifest too — it has no meaning once Delivery OS is
-  // gone, and leaving it behind would make a later install/status think a
-  // stale version is still installed.
+  // Remove the version manifest too — but only once nothing Delivery-OS-
+  // related actually remains. Templates and the skill are kept by default
+  // (only removed with their own flags), and if they're still on disk, the
+  // manifest's version is still meaningful for them — deleting it would make
+  // a later `status` report "unknown version" for files that are, in fact,
+  // still fully present and version-tracked.
+  const anyWorkflowsRemain = WORKFLOWS.some((wf) => fs.existsSync(path.join(workflowsDest, `${wf}.yml`)));
+  const anyTemplatesRemain = TEMPLATES.some((t) => fs.existsSync(path.join(templatesDest, t)));
+  // Scripts are removed unconditionally just above, so this is normally
+  // always false by the time we get here — included anyway for the same
+  // reason the other three are checked explicitly rather than assumed:
+  // defensive completeness against a future change (e.g. a failed unlink,
+  // or script removal ever becoming flag-gated like templates/skill).
+  const anyScriptsRemain = SCRIPTS.some((name) => fs.existsSync(path.join(scriptsDest, `${name}.js`)));
+  const skillRemains = fs.existsSync(skillPath(targetAbs));
+  const nothingLeft = !anyWorkflowsRemain && !anyTemplatesRemain && !anyScriptsRemain && !skillRemains;
+
   const manifestDest = manifestPath(targetAbs);
-  if (fs.existsSync(manifestDest)) {
+  if (nothingLeft && fs.existsSync(manifestDest)) {
     if (dryRun) {
       console.log('  [dry-run] Would remove: delivery-os.json');
     } else {
@@ -528,6 +662,9 @@ function runUninstall(options) {
       if (!withSkill) {
         console.log('Claude Code skill (if installed) was kept. Re-run with --with-skill to remove it.');
       }
+      if (!nothingLeft) {
+        console.log('delivery-os.json was kept — something Delivery-OS-related is still on disk.');
+      }
     }
   } else {
     console.log('No Delivery OS files found to remove.');
@@ -550,5 +687,7 @@ module.exports = {
     SKILL_REL_PATH,
     WORKFLOWS,
     TEMPLATES,
+    SCRIPTS,
+    REQUIRED_SCRIPT_BY_WORKFLOW,
   },
 };