github-delivery-os 1.0.2 → 1.1.0

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

@@ -6,6 +6,7 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   authorize:
@@ -13,8 +14,22 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the verdict script can be required from the repo
+    # Serialize per-issue: two comments posted seconds apart (e.g. a decline
+    # immediately corrected with an approval) can trigger overlapping runs.
+    # Both would recompute the same final verdict correctly, but each reads
+    # its "already posted?" check from the stale label snapshot on its own
+    # triggering event, so without this they could both post a status
+    # comment. Scoped per issue (not per repo) so unrelated releases still
+    # process concurrently.
+    concurrency:
+      group: authorize-deployment-${{ github.event.issue.number }}
+      cancel-in-progress: false
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Check Dual Approval (Flexible + Decline)
         uses: actions/github-script@v7
         env:
@@ -22,81 +37,79 @@ jobs:
           QA_APPROVER: ${{ vars.QA_APPROVER || 'qa-approver' }}
         with:
           script: |
+            // Pure verdict logic lives in a real, unit-tested module (see
+            // .github/scripts/authorize-deployment-verdict.js and
+            // test/authorize-deployment-verdict.test.js) rather than inline here,
+            // so it isn't only verified by hand whenever it changes.
+            const { computeVerdict } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/authorize-deployment-verdict.js`);
+
             const issueNumber = context.issue.number;
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const releaseApprover = process.env.RELEASE_APPROVER;
             const qaApprover = process.env.QA_APPROVER;
 
-            const comments = await github.rest.issues.listComments({
+            const comments = await github.paginate(github.rest.issues.listComments, {
               owner,
               repo,
-              issue_number: issueNumber
+              issue_number: issueNumber,
+              per_page: 100
             });
 
-            let releaseApproved = false;
-            let qaApproved = false;
-
-            for (const comment of comments.data) {
-              const body = (comment.body || "").trim().toLowerCase();
+            const { releaseVerdict, qaApproved } = computeVerdict(comments, releaseApprover, qaApprover);
 
-              if (
-                comment.user.login === releaseApprover &&
-                /(declined|reject|not approved)/i.test(body)
-              ) {
+            const currentLabels = (context.payload.issue.labels || []).map((l) => l.name);
+            const alreadyDeclined = currentLabels.includes("declined");
+            const alreadyReady = currentLabels.includes("ready-for-deploy");
 
-                await github.rest.issues.addLabels({
-                  owner,
-                  repo,
-                  issue_number: issueNumber,
-                  labels: ["declined"]
-                });
+            if (releaseVerdict === "declined") {
+              if (alreadyDeclined) return; // avoid re-posting on every later comment
 
-                try {
-                  await github.rest.issues.removeLabel({
-                    owner,
-                    repo,
-                    issue_number: issueNumber,
-                    name: "ready-for-deploy"
-                  });
-                } catch (e) {}
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                labels: ["declined"]
+              });
 
-                await github.rest.issues.createComment({
+              try {
+                await github.rest.issues.removeLabel({
                   owner,
                   repo,
                   issue_number: issueNumber,
-                  body: "🔴 **Release Declined**\n\nThis release requires additional fixes before production deployment."
+                  name: "ready-for-deploy"
                 });
+              } catch (e) {}
+
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                body: "🔴 **Release Declined**\n\nThis release requires additional fixes before production deployment."
+              });
 
-                return;
-              }
-
-              if (
-                comment.user.login === releaseApprover &&
-                /^(approved|approve|ok|go ahead)/i.test(body)
-              ) {
-                releaseApproved = true;
-              }
-
-              if (
-                comment.user.login === qaApprover &&
-                /(qa approved|approved|qa ok|looks good)/i.test(body)
-              ) {
-                qaApproved = true;
-              }
+              return;
             }
 
-            if (releaseApproved && qaApproved) {
+            if (releaseVerdict === "approved" && qaApproved) {
+              if (alreadyReady) return; // avoid re-posting on every later comment
 
               try {
-                await github.rest.issues.addLabels({
+                await github.rest.issues.removeLabel({
                   owner,
                   repo,
                   issue_number: issueNumber,
-                  labels: ["ready-for-deploy"]
+                  name: "declined"
                 });
               } catch (e) {}
 
+              await github.rest.issues.addLabels({
+                owner,
+                repo,
+                issue_number: issueNumber,
+                labels: ["ready-for-deploy"]
+              });
+
               await github.rest.issues.createComment({
                 owner,
                 repo,

package/.github/workflows/auto-assign-qa.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       # pozil/auto-assign-issue does not support 'labels' input; labels come from issue template (qa_request.yml)
       - name: Assign QA team to QA submission issues
-        uses: pozil/auto-assign-issue@v1
+        uses: pozil/auto-assign-issue@d11e715efc663fe323c3d8d4d3cbbfdddd539baf # v1
         with:
           assignees: ${{ vars.QA_ASSIGNEES }}
           repo-token: ${{ secrets.GITHUB_TOKEN }}

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

@@ -6,14 +6,25 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   update-sprint:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the burn-down script can be required from the repo
+    # Serialize runs: closing several child issues in quick succession triggers
+    # concurrent runs that each read-modify-write the same sprint issue body,
+    # which can race and drop an update (or double-fire the 100% auto-close).
+    concurrency:
+      group: auto-close-sprint-${{ github.repository }}
+      cancel-in-progress: false
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Update sprint health, burn-down, and auto-close
         uses: actions/github-script@v7
         env:
@@ -21,13 +32,25 @@ jobs:
           TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}
         with:
           script: |
+            // Pure burn-down/health logic lives in a real, unit-tested module
+            // (see .github/scripts/auto-close-sprint.js and
+            // test/auto-close-sprint.test.js) rather than inline here, so
+            // it isn't only verified by hand whenever it changes.
+            const {
+              parseParentSprintNumber,
+              parseSprintDates,
+              computeTimePercent,
+              computeProgress,
+              computeHealthEmoji,
+              renderBurnDown,
+              updateSprintBody,
+            } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/auto-close-sprint.js`);
+
             const issue = context.payload.issue;
             const body = issue.body || "";
 
-            const parentMatch = body.match(/Parent Sprint:\s*#(\d+)/);
-            if (!parentMatch) return;
-
-            const sprintNumber = parseInt(parentMatch[1]);
+            const sprintNumber = parseParentSprintNumber(body);
+            if (!sprintNumber) return;
 
             const sprintIssue = await github.rest.issues.get({
               owner: context.repo.owner,
@@ -37,31 +60,27 @@ jobs:
 
             const sprintBody = sprintIssue.data.body || "";
 
-            let startDate, endDate;
-            const dateMatch1 = sprintBody.match(/Sprint Dates[\s\S]*?(\d{4}-\d{2}-\d{2})\s*to\s*(\d{4}-\d{2}-\d{2})/i);
-            const dateMatch2a = sprintBody.match(/Sprint Start[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
-            const dateMatch2b = sprintBody.match(/Sprint End[\s\S]*?(\d{4}-\d{2}-\d{2})/i);
-            if (dateMatch1) {
-              startDate = new Date(dateMatch1[1]);
-              endDate = new Date(dateMatch1[2]);
-            } else if (dateMatch2a && dateMatch2b) {
-              startDate = new Date(dateMatch2a[1]);
-              endDate = new Date(dateMatch2b[1]);
-            }
-            if (!startDate || !endDate) {
+            const dates = parseSprintDates(sprintBody);
+            if (!dates) {
               console.log("Sprint dates not found.");
               return;
             }
-            const now = new Date();
-
-            const totalDuration = endDate - startDate;
-            const elapsed = now - startDate;
-            const timePercent = Math.max(0, Math.min(100, Math.round((elapsed / totalDuration) * 100)));
 
-            const { data: allIssues } = await github.rest.issues.listForRepo({
+            const timePercent = computeTimePercent(dates.startDate, dates.endDate, new Date());
+
+            // 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.
+            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
             });
 
@@ -69,31 +88,10 @@ jobs:
               i.body && i.body.includes(`Parent Sprint: #${sprintNumber}`)
             );
 
-            const closedChildren = children.filter(i => i.state === "closed");
-
-            const progressPercent = children.length === 0
-              ? 0
-              : Math.round((closedChildren.length / children.length) * 100);
-
-            let healthEmoji = "🟢";
-            if (progressPercent < timePercent - 10) healthEmoji = "🔴";
-            else if (progressPercent < timePercent) healthEmoji = "🟡";
-
-            const totalBars = 20;
-            const filledBars = Math.round((progressPercent / 100) * totalBars);
-            const burnDown =
-              "█".repeat(filledBars) + "░".repeat(totalBars - filledBars);
-
-            let updatedBody = sprintBody;
-            updatedBody = updatedBody.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---`;
+            const { progressPercent } = computeProgress(children);
+            const healthEmoji = computeHealthEmoji(progressPercent, timePercent);
+            const burnDown = renderBurnDown(progressPercent);
+            const updatedBody = updateSprintBody(sprintBody, { progressPercent, timePercent, healthEmoji, burnDown });
 
             await github.rest.issues.update({
               owner: context.repo.owner,

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/.github/workflows/pages.yml

@@ -0,0 +1,46 @@
+# Deploy docs/ to GitHub Pages
+# Requires: Settings → Pages → Source: GitHub Actions
+
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Opt into Node.js 24
+        run: echo "FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true" >> $GITHUB_ENV
+
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/release.yml

@@ -15,10 +15,21 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
       - name: Create Release
         uses: softprops/action-gh-release@v2
         with:

package/.github/workflows/sprint-child-creator.yml

@@ -6,6 +6,7 @@ on:
 
 permissions:
   issues: write
+  contents: read
 
 jobs:
   create-child-issues:
@@ -13,25 +14,30 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       issues: write
+      contents: read # needed for actions/checkout, so the parser script can be required from the repo
 
     steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
       - name: Create Child Issues
         uses: actions/github-script@v7
         with:
           script: |
+            // Pure parsing logic lives in a real, unit-tested module (see
+            // .github/scripts/sprint-child-creator.js and
+            // test/sprint-child-creator.test.js) rather than inline here, so
+            // it isn't only verified by hand whenever it changes.
+            const { parseFeatures, buildChildBody } = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/sprint-child-creator.js`);
+
             const issue = context.payload.issue;
             const body = issue.body || "";
             const parentNumber = issue.number;
 
-            const featuresMatch = body.match(/### Sprint Features[\s\S]*?(?=###|$)/);
-            if (!featuresMatch) return;
-
-            const features = featuresMatch[0]
-              .split('\n')
-              .map(line => line.trim())
-              .filter(line => line && !line.startsWith('###'));
+            const features = parseFeatures(body);
+            if (features.length === 0) return;
 
-            const bodyContent = `Parent Sprint: #${parentNumber}\n\n---\n*Created by Delivery OS Sprint Child Creator*`;
+            const bodyContent = buildChildBody(parentNumber);
 
             for (const title of features) {
               await github.rest.issues.create({

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

@@ -100,10 +100,17 @@ jobs:
             URL="${ISSUE_URL}"
             COMMENT=$(echo "$COMMENT_BODY" | head -c 300)
 
-            if [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "declined\|reject\|not approved"; then
+            # 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
               MESSAGE="🔴🛑 RELEASE DECLINED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "$ACTOR" == "$RELEASE_APPROVER" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; then
+            elif [[ "${ACTOR,,}" == "${RELEASE_APPROVER,,}" ]] && echo "$COMMENT_BODY" | grep -iq "^approved"; 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/README.md

@@ -35,7 +35,7 @@ From your repo root. Add `--with-labels` to create labels via `gh` CLI (requires
 **Alternative — clone and run script:**
 
 ```bash
-git clone https://github.com/jkaweesi22/github-delivery-operating-system
+git clone https://github.com/Phaneroo/github-delivery-operating-system
 cd github-delivery-operating-system
 
 # New install or repo with existing workflows — adds only missing files (safe)
@@ -52,11 +52,15 @@ cd github-delivery-operating-system
 
 **Other commands:**
 ```bash
-npx github-delivery-os status .          # Show what's installed
-npx github-delivery-os uninstall .      # Remove workflows
+npx github-delivery-os status .                    # Show what's installed + installed version
+npx github-delivery-os status --offline .          # Same, without checking npm for updates
+npx github-delivery-os uninstall .                 # Remove workflows
 npx github-delivery-os uninstall --with-templates .  # Remove workflows + templates
+npx github-delivery-os uninstall --dry-run .      # Preview (no changes)
 ```
 
+`status` also checks npm for a newer release and tells you if you're behind (e.g. `⬆️ Update available: 1.0.3 → 1.1.0`), along with the exact command to update. That check is silent and non-fatal if you're offline — use `--offline` to skip it outright (e.g. in CI).
+
 **What gets installed:**
 
 | Workflow | Purpose |
@@ -71,6 +75,8 @@ npx github-delivery-os uninstall --with-templates .  # Remove workflows + templa
 
 Workflows and templates are **copied directly** into your repo. No `workflow_call` or external references.
 
+Installing via `npx github-delivery-os` (not the `scripts/install.sh` clone path) also writes `.github/delivery-os.json`, a small manifest recording the installed version — this is what powers the update check in `status`. It's only written when the files it describes are actually current (a fresh install, or `--overwrite`); a skip-mode install over existing files leaves it untouched rather than claiming a version that isn't really on disk. `uninstall` removes it.
+
 ---
 
 ## Quick Start (After Install)
@@ -100,7 +106,9 @@ When you open an issue using the **Sprint Planning** template with a title like
 
 | Document | Description |
 |----------|-------------|
-| **[Landing page & quick start](https://jkaweesi22.github.io/github-delivery-operating-system/)** | Overview, one-command install, features |
+| **[Landing page & quick start](https://phaneroo.github.io/github-delivery-operating-system/)** | Overview, one-command install, features |
+| [PRFAQ](docs/PRFAQ.md) | Product overview and FAQs for all audiences (npm launch, install, governance) |
+| [Press release (npm)](docs/press-release.md) | Formal announcement: Delivery OS on npm |
 | [Consumer Setup](docs/consumer-setup.md) | Installation, configuration, variables, labels, Telegram, uninstall |
 | [How To](docs/how-to.md) | Create sprints, request releases, approve, report bugs, QA requests |
 | [Architecture](docs/architecture.md) | Workflows, templates, data flow |

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "github-delivery-os",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {
     "delivery-os": "./bin/delivery-os.js"
   },
   "scripts": {
-    "install:local": "node bin/delivery-os.js install --with-templates ."
+    "install:local": "node bin/delivery-os.js install --with-templates .",
+    "test": "node test/run.js"
   },
   "keywords": [
     "github",
@@ -28,11 +29,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jkaweesi22/github-delivery-operating-system"
+    "url": "https://github.com/Phaneroo/github-delivery-operating-system"
   },
-  "homepage": "https://jkaweesi22.github.io/github-delivery-operating-system/",
+  "homepage": "https://phaneroo.github.io/github-delivery-operating-system/",
   "bugs": {
-    "url": "https://github.com/jkaweesi22/github-delivery-operating-system/issues"
+    "url": "https://github.com/Phaneroo/github-delivery-operating-system/issues"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -37,8 +37,9 @@ program
 program
   .command('status [target]')
   .description('Show which workflows and templates are installed')
-  .action((target) => {
-    runStatus({ targetDir: target || '.' });
+  .option('--offline', 'Skip checking npm for the latest published version')
+  .action(async (target, options) => {
+    await runStatus({ targetDir: target || '.', checkUpdates: !options.offline });
   });
 
 program
@@ -54,7 +55,13 @@ program
     });
   });
 
-program.parse();
+// parseAsync (not parse) because the `status` action is async — with plain
+// parse(), an error thrown inside it becomes an unhandled rejection that
+// Node <15 does not treat as fatal, so a real failure could exit 0.
+program.parseAsync().catch((err) => {
+  console.error(err && err.message ? err.message : err);
+  process.exitCode = 1;
+});
 
 // Show help if no command
 if (!process.argv.slice(2).length) {

package/src/install.js

@@ -1,7 +1,10 @@
 const path = require('path');
 const fs = require('fs');
+const https = require('https');
 const { execFileSync } = require('child_process');
 
+const MANIFEST_FILE = 'delivery-os.json'; // written to .github/delivery-os.json in the target repo
+
 const WORKFLOWS = [
   'sprint-child-creator',
   'auto-close-sprint',
@@ -30,6 +33,65 @@ const LABELS = [
   ['risk', 'B60205'],
 ];
 
+function manifestPath(targetAbs) {
+  return path.join(targetAbs, '.github', MANIFEST_FILE);
+}
+
+function readManifest(targetAbs) {
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath(targetAbs), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeManifest(targetAbs, version) {
+  const dest = manifestPath(targetAbs);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(
+    dest,
+    JSON.stringify({ version, installedAt: new Date().toISOString() }, null, 2) + '\n'
+  );
+}
+
+// Best-effort check against the npm registry. Never throws or rejects —
+// resolves null on any failure (offline, registry down, timeout) so callers
+// can treat "unknown" and "couldn't check" identically with no extra
+// error-handling of their own.
+function fetchLatestVersion(timeoutMs = 3000) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const req = https.get(
+      'https://registry.npmjs.org/github-delivery-os/latest',
+      { headers: { 'User-Agent': 'github-delivery-os-cli' } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          done(null);
+          return;
+        }
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            done(JSON.parse(data).version || null);
+          } catch {
+            done(null);
+          }
+        });
+      }
+    );
+    req.setTimeout(timeoutMs, () => req.destroy());
+    req.on('error', () => done(null));
+  });
+}
+
 function getPackageRoot() {
   // When installed via npm, __dirname is node_modules/github-delivery-os/src
   const possibleRoots = [
@@ -86,6 +148,8 @@ function runInstall(options) {
 
   let workflowsCopied = 0;
   let templatesCopied = 0;
+  let workflowsSkipped = 0;
+  let templatesSkipped = 0;
 
   // Copy workflows
   for (const wf of WORKFLOWS) {
@@ -99,6 +163,7 @@ function runInstall(options) {
 
     if (fs.existsSync(dest) && !overwrite) {
       console.log(`  Skipped (exists): ${wf}.yml`);
+      workflowsSkipped++;
     } else if (dryRun) {
       console.log(`  [dry-run] Would create: ${wf}.yml`);
       workflowsCopied++;
@@ -120,6 +185,7 @@ function runInstall(options) {
 
       if (fs.existsSync(dest) && !overwrite) {
         console.log(`  Skipped (exists): ${name}`);
+        templatesSkipped++;
       } else if (dryRun) {
         console.log(`  [dry-run] Would create template: ${name}`);
         templatesCopied++;
@@ -192,8 +258,26 @@ 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);
+  if (!dryRun && cleanInstall) {
+    const pkgVersion = require(path.join(pkgRoot, 'package.json')).version;
+    writeManifest(targetAbs, pkgVersion);
+  }
+
   // 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.');
+    console.log('');
+  }
   if (workflowsCopied > 0 || templatesCopied > 0 || labelsCreated > 0) {
     if (dryRun) {
       if (workflowsCopied > 0) console.log(`Would install ${workflowsCopied} workflow(s).`);
@@ -216,7 +300,7 @@ function runInstall(options) {
       console.log('  4. Copy templates: re-run with --with-templates');
     }
     console.log('');
-    console.log('See https://jkaweesi22.github.io/github-delivery-operating-system/ for full docs.');
+    console.log('See https://phaneroo.github.io/github-delivery-operating-system/ for full docs.');
   } else {
     if (dryRun) {
       console.log('Dry run complete. No files were changed.');
@@ -238,8 +322,8 @@ const TEMPLATES = [
   'bug_report.yml',
 ];
 
-function runStatus(options) {
-  const { targetDir = '.' } = options;
+async function runStatus(options) {
+  const { targetDir = '.', checkUpdates = true } = options;
   const targetAbs = path.resolve(process.cwd(), targetDir);
   const workflowsDest = path.join(targetAbs, '.github', 'workflows');
   const templatesDest = path.join(targetAbs, '.github', 'ISSUE_TEMPLATE');
@@ -255,6 +339,32 @@ function runStatus(options) {
     fs.existsSync(path.join(templatesDest, t))
   );
 
+  if (installedWorkflows.length > 0 || installedTemplates.length > 0) {
+    const manifest = readManifest(targetAbs);
+    if (manifest && manifest.version) {
+      const installedOn = manifest.installedAt ? ` (installed ${manifest.installedAt.slice(0, 10)})` : '';
+      console.log(`Installed version: ${manifest.version}${installedOn}`);
+    } else {
+      console.log('Installed version: unknown (installed before version tracking was added)');
+      console.log('  Run install with --overwrite to record the current version.');
+    }
+
+    if (checkUpdates) {
+      const latest = await fetchLatestVersion();
+      if (!latest) {
+        console.log('  (Could not check npm for the latest version — offline or registry unreachable.)');
+      } else if (manifest && manifest.version === latest) {
+        console.log(`✓ Up to date (latest is ${latest})`);
+      } else if (manifest && manifest.version) {
+        console.log(`⬆️  Update available: ${manifest.version} → ${latest}`);
+        console.log('    Run: npx github-delivery-os@latest install --overwrite .');
+      } else {
+        console.log(`Latest published version: ${latest}`);
+      }
+    }
+    console.log('');
+  }
+
   if (installedWorkflows.length > 0) {
     console.log('Workflows:');
     installedWorkflows.forEach((wf) => console.log(`  ✓ ${wf}.yml`));
@@ -325,6 +435,19 @@ 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.
+  const manifestDest = manifestPath(targetAbs);
+  if (fs.existsSync(manifestDest)) {
+    if (dryRun) {
+      console.log('  [dry-run] Would remove: delivery-os.json');
+    } else {
+      fs.unlinkSync(manifestDest);
+      console.log('  Removed: delivery-os.json');
+    }
+  }
+
   console.log('');
   if (workflowsRemoved > 0 || templatesRemoved > 0) {
     if (dryRun) {
@@ -342,4 +465,10 @@ function runUninstall(options) {
   console.log('=== Uninstall complete ===');
 }
 
-module.exports = { runInstall, runStatus, runUninstall };
+module.exports = {
+  runInstall,
+  runStatus,
+  runUninstall,
+  // Exposed for tests only — not part of the CLI's public API.
+  __test__: { manifestPath, readManifest, writeManifest, fetchLatestVersion, WORKFLOWS, TEMPLATES },
+};