github-delivery-os 1.4.1 → 1.5.0

package/.claude/skills/delivery-ops/SKILL.md

@@ -21,7 +21,7 @@ Creating issues and comments in a repo is a visible, outward action — other co
 Before creating anything that depends on configuration, check the target repo actually has Delivery OS installed and configured — a silent no-op (nothing happens because a variable is unset) is more confusing than an upfront "this won't do much yet":
 
 - **Installed?** `gh api repos/<owner>/<repo>/contents/.github/workflows/authorize-deployment.yml --silent` (404 = not installed — suggest `npx github-delivery-os status .` or `install --with-templates` in that repo).
-- **Labels set up?** `gh label list --repo <owner>/<repo>` — look for `production`, `qa`, `qa-request`, `sprint`, `sprint-active`, `planning`, `declined`, `ready-for-deploy`. Missing labels mean `Setup Labels` hasn't been run there yet — offer to fix it directly rather than just reporting the gap: `gh workflow run setup-labels.yml --repo <owner>/<repo>` (it's a `workflow_dispatch` trigger, so this actually creates them on the spot). Confirm with the user first since it's a real change to their repo.
+- **Labels set up?** `gh label list --repo <owner>/<repo>` — look for `production`, `qa`, `qa-request`, `sprint`, `sprint-child`, `planning`, `declined`, `ready-for-deploy`. Missing labels mean `Setup Labels` hasn't been run there yet — offer to fix it directly rather than just reporting the gap: `gh workflow run setup-labels.yml --repo <owner>/<repo>` (it's a `workflow_dispatch` trigger, so this actually creates them on the spot). Confirm with the user first since it's a real change to their repo. (`sprint-active` instead of `sprint-child` means the repo is on a pre-1.5.0 install — still valid, just the older label name.)
 - **Repo variables set?** `gh variable list --repo <owner>/<repo>` — look for `RELEASE_APPROVER`, `QA_APPROVER`, `QA_ASSIGNEES`. If unset, say so plainly: the issue will still get created, but `notify-release-approver` will ping the literal placeholder `release-approver`/`qa-approver`, not a real person. Setting these requires repo admin access (`gh variable set NAME --repo <owner>/<repo> --body <value>`) — don't set them without being asked to, since they name a real person as approver.
 
 ## Creating issues
@@ -32,7 +32,7 @@ Before creating anything that depends on configuration, check the target repo ac
 
 This confirm-first default is for issues created **on explicit request** ("file a bug for this", "create a sprint"). The "Autonomous tracking" section below describes a *different* mode — noticing and filing work on its own during a session — and overrides this default there: act first, confirm after, per its own "Confirm only when unsure" rule. Don't apply both rules to the same action.
 
-**Sprint Planning** — triggers `sprint-child-creator` (one child issue per feature line, each labeled `sprint-active`, on open):
+**Sprint Planning** — triggers `sprint-child-creator` (one child issue per feature line, each labeled `sprint-child` — `sprint-active` on repos installed before 1.5.0 — on open):
 - Title **must contain** the literal string `SPRINT -`, e.g. `SPRINT - Sprint 14`
 - Labels: `sprint`, `planning`
 - Body:
@@ -163,7 +163,7 @@ Closing a sprint task (child) issue is what actually moves the burn-down — cre
 gh issue close <number> --repo <owner>/<repo>
 ```
 
-`auto-close-sprint` fires on close, re-reads every `sprint-active` issue whose body contains `Parent Sprint: #<N>`, recomputes progress, and rewrites the sprint issue's `## 🚦 Sprint Status` section. At 100% it also closes the sprint issue itself and posts a completion comment. Re-check the sprint issue's body afterward to see the update — it happens as a side effect of closing the child, not as a response visible on the child issue itself.
+`auto-close-sprint` fires on close, re-reads every issue whose body contains `Parent Sprint: #<N>` (label-independent — see below), recomputes progress, and rewrites the sprint issue's `## 🚦 Sprint Status` section. At 100% it also closes the sprint issue itself and posts a completion comment. Re-check the sprint issue's body afterward to see the update — it happens as a side effect of closing the child, not as a response visible on the child issue itself.
 
 ## Autonomous tracking (identify → file → update → close)
 
@@ -201,7 +201,7 @@ Don't rely on recalling an issue number from earlier in the conversation, and ne
 gh issue list --repo <owner>/<repo> --state open --search "<keywords from the work>"
 ```
 
-Narrow with `--label task` (or `bug`, `sprint-active`, `qa-request`) only once the category is known and the target repo actually has that label — don't assume `--label task` alone finds everything relevant.
+Narrow with `--label task` (or `bug`, `sprint-child`, `qa-request`) only once the category is known and the target repo actually has that label — don't assume `--label task` alone finds everything relevant. (Older repos may still use `sprint-active` instead of `sprint-child`; check `gh label list` first.)
 
 This is also what makes picking work back up in a *new* session possible without any local memory — the issue list itself is the state.
 
@@ -232,7 +232,7 @@ Given an SRS/PRD, or just a plain-language feature description, break it into a
 
 3. **Per phase, once confirmed:**
    - Create the Sprint Planning issue with the usual recipe (`SPRINT - <phase name>`, dates, goal). "Sprint Features (One Per Line)" is template-required, so it can't be left empty — put one line noting the real breakdown is in linked Task issues (e.g. `See linked Task issues for this phase's breakdown`). This means exactly one bare placeholder child gets auto-created.
-   - File one full Task issue per requirement (the usual Task recipe — Owner, Priority, Acceptance Criteria drawn from the spec text; ask only when the spec genuinely doesn't specify something, like priority). Include `Parent Sprint: #<sprint-number>` in the body (e.g. under Artifacts / Links) — that exact phrase is what `auto-close-sprint` actually scans for (`.github/workflows/auto-close-sprint.yml` filters on body content only, **not** the `sprint-active` label, deliberately — see its own comment on why label-scoping was tried and reverted). Add the `sprint-active` label anyway, for consistency with how the sprint's own children are found (see "Finding things" below), but know it plays no role in the burn-down count.
+   - File one full Task issue per requirement (the usual Task recipe — Owner, Priority, Acceptance Criteria drawn from the spec text; ask only when the spec genuinely doesn't specify something, like priority). Include `Parent Sprint: #<sprint-number>` in the body (e.g. under Artifacts / Links) — that exact phrase is what `auto-close-sprint` actually scans for (`.github/workflows/auto-close-sprint.yml` filters on body content only, **not** the `sprint-child` label, deliberately — see its own comment on why label-scoping was tried and reverted). Add the `sprint-child` label anyway, for consistency with how the sprint's own children are found (see "Finding things" below), but know it plays no role in the burn-down count.
    - Now that the real Task issues exist, close the one placeholder child: `gh issue close <N> --repo <owner>/<repo> --comment "Superseded by full Task issues for this phase — see #.., #.., #.."`, filling in the actual issue numbers just created. Otherwise the placeholder sits in the sprint's burn-down denominator as an item that can never represent real completed work, and the sprint can never legitimately reach 100%.
 
 4. **Report back everything created**, grouped by phase — sprint issue number, task issue numbers, and the placeholder-close.
@@ -245,4 +245,4 @@ When there's no issue number in hand yet:
 - **Production releases awaiting a decision:** `gh issue list --repo <owner>/<repo> --label production --state open`
 - **Active sprints:** `gh issue list --repo <owner>/<repo> --label sprint --state open` (title contains `SPRINT -`)
 - **Open QA requests:** `gh issue list --repo <owner>/<repo> --label qa-request --state open`
-- **A sprint's own children:** `gh issue list --repo <owner>/<repo> --label sprint-active --search "\"Parent Sprint: #<N>\" in:body"` — the exact-phrase quotes matter, otherwise the search matches "Parent", "Sprint", and the number as separate free-text terms instead of the literal phrase
+- **A sprint's own children:** `gh issue list --repo <owner>/<repo> --label sprint-child --search "\"Parent Sprint: #<N>\" in:body"` — the exact-phrase quotes matter, otherwise the search matches "Parent", "Sprint", and the number as separate free-text terms instead of the literal phrase. On a repo installed before 1.5.0 (or one that hasn't run the `gh label edit` migration — see `docs/consumer-setup.md`), use `--label sprint-active` instead, or drop `--label` entirely and rely on the body search alone if you're not sure which name applies.

package/.github/workflows/setup-labels.yml

@@ -26,7 +26,7 @@ jobs:
               { name: 'intake', color: '0E8A16' },
               { name: 'bug', color: 'D93F0B' },
               { name: 'sprint', color: '1D76DB' },
-              { name: 'sprint-active', color: '1D76DB' },
+              { name: 'sprint-child', color: '1D76DB', description: "Applied to a sprint's task-breakdown children on open; doesn't change when the sprint closes" },
               { name: 'planning', color: '5319E7' },
               { name: 'sprint-planning', color: '5319E7' },
               { name: 'task', color: '7057FF' },
@@ -40,13 +40,14 @@ jobs:
               { name: 'risk', color: 'B60205' },
             ];
             let created = 0;
-            for (const { name, color } of labels) {
+            for (const { name, color, description } of labels) {
               try {
                 await github.rest.issues.createLabel({
                   owner: context.repo.owner,
                   repo: context.repo.repo,
                   name,
                   color,
+                  ...(description ? { description } : {}),
                 });
                 console.log(`Created: ${name}`);
                 created++;

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

@@ -45,6 +45,6 @@ jobs:
                 repo: context.repo.repo,
                 title,
                 body: bodyContent,
-                labels: ['sprint-active']
+                labels: ['sprint-child']
               });
             }

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

@@ -77,7 +77,10 @@ jobs:
               fi
             fi
 
-            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
+            # sprint-active is the pre-1.5.0 label name; still checked here so
+            # issues created before a repo upgrades don't go silent on close.
+            if [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-child') }}" == "true" ]] || \
+               [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
               if [ "$ACTION" = "opened" ]; then
                 MESSAGE="🟡🛠️ SPRINT TASK CREATED%0A$TITLE%0A$URL%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
               elif [ "$ACTION" = "closed" ]; then
@@ -129,7 +132,8 @@ jobs:
             elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'production') }}" == "true" ]]; then
               MESSAGE="💬🚀 RELEASE COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
 
-            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
+            elif [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-child') }}" == "true" ]] || \
+                 [[ "${{ contains(github.event.issue.labels.*.name || fromJSON('[]'), 'sprint-active') }}" == "true" ]]; then
               MESSAGE="💬🛠️ SPRINT TASK COMMENT%0A$TITLE%0A$URL%0A---%0A$COMMENT%0A---%0A👤 $ACTOR%0A🕒 $TIMESTAMP"
             fi
           fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-delivery-os",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "A GitHub-native Delivery Governance Framework for structured sprint execution, QA review, and collaborative production release control.",
   "main": "src/install.js",
   "bin": {

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { program } = require('commander');
+const { program, Option } = require('commander');
 const path = require('path');
 const fs = require('fs');
 const { runInstall, runStatus, runUninstall } = require('./install');
@@ -21,8 +21,12 @@ program
   .option('-t, --with-templates', 'Copy issue templates (sprint, task, bug, QA, production release)')
   .option('-l, --with-labels', 'Create labels via gh CLI (requires gh auth)')
   .option('-s, --with-skill', 'Add the delivery-ops Claude Code skill (.claude/skills/delivery-ops/SKILL.md)')
-  .option('-o, --overwrite', 'Replace existing workflow/template files')
-  .option('--no-overwrite', 'Skip existing files (default)')
+  .option('-u, --update', 'Replace existing workflow/template files with the latest version')
+  .option('--no-update', 'Skip existing files (default)')
+  // Pre-1.5.0 names, kept working silently so existing scripts/CI calling
+  // `install --overwrite` don't break — --update is the documented name now.
+  .addOption(new Option('-o, --overwrite').hideHelp())
+  .addOption(new Option('--no-overwrite').hideHelp())
   .option('-d, --dry-run', 'Show what would happen without changing files')
   .action((target, options) => {
     const targetDir = target || '.';
@@ -31,7 +35,7 @@ program
       withTemplates: options.withTemplates ?? false,
       withLabels: options.withLabels ?? false,
       withSkill: options.withSkill ?? false,
-      overwrite: options.overwrite ?? false,
+      overwrite: options.update ?? options.overwrite ?? false,
       dryRun: options.dryRun ?? false,
     });
   });

package/src/install.js

@@ -51,7 +51,7 @@ const LABELS = [
   ['intake', '0E8A16'],
   ['bug', 'D93F0B'],
   ['sprint', '1D76DB'],
-  ['sprint-active', '1D76DB'],
+  ['sprint-child', '1D76DB', "Applied to a sprint's task-breakdown children on open; doesn't change when the sprint closes"],
   ['planning', '5319E7'],
   ['sprint-planning', '5319E7'],
   ['task', '7057FF'],
@@ -351,9 +351,11 @@ function runInstall(options) {
       }
 
       if (!labelsSkipReason) {
-        for (const [name, color] of LABELS) {
+        for (const [name, color, description] of LABELS) {
           try {
-            execFileSync('gh', ['label', 'create', name, '--color', color], {
+            const args = ['label', 'create', name, '--color', color];
+            if (description) args.push('--description', description);
+            execFileSync('gh', args, {
               cwd: targetAbs,
               stdio: 'pipe',
             });
@@ -406,11 +408,11 @@ function runInstall(options) {
     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('  version was not updated. Re-run with --update 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('  Delivery OS version was not updated. Re-run with --update to sync');
       console.log('  all files (and the recorded version) to the latest release.');
     }
     console.log('');
@@ -453,7 +455,7 @@ function runInstall(options) {
       console.log('Dry run complete. No files were changed.');
     } else {
       console.log('No new files created (existing files were skipped).');
-      console.log('To update: use --overwrite (run with --dry-run first to preview).');
+      console.log('To update: use --update (run with --dry-run first to preview).');
     }
   }
   console.log('');
@@ -464,11 +466,11 @@ function runInstall(options) {
 // installed actually gets touched this run (see the cleanInstall check
 // there) — so a repo with templates and/or the skill already on disk needs
 // --with-templates/--with-skill passed again on an update, not just
-// --overwrite, or the recorded version never advances and `status` keeps
+// --update, or the recorded version never advances and `status` keeps
 // suggesting the same command forever. Build the hint from what's actually
 // on disk so it's never wrong.
-function buildOverwriteCommand({ hasTemplates, hasSkill }) {
-  const flags = [hasTemplates ? '--with-templates' : null, hasSkill ? '--with-skill' : null, '--overwrite']
+function buildUpdateCommand({ hasTemplates, hasSkill }) {
+  const flags = [hasTemplates ? '--with-templates' : null, hasSkill ? '--with-skill' : null, '--update']
     .filter(Boolean)
     .join(' ');
   return `npx github-delivery-os@latest install ${flags} .`;
@@ -533,7 +535,7 @@ async function runStatus(options) {
     } else {
       console.log('Installed version: unknown (installed before version tracking was added)');
       console.log(
-        `  Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+        `  Run: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
       );
     }
 
@@ -546,7 +548,7 @@ async function runStatus(options) {
       } else if (manifest && manifest.version) {
         console.log(`⬆️  Update available: ${manifest.version} → ${latest}`);
         console.log(
-          `    Run: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+          `    Run: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
         );
       } else {
         console.log(`Latest published version: ${latest}`);
@@ -568,7 +570,7 @@ async function runStatus(options) {
     });
     console.log('  That workflow will fail with MODULE_NOT_FOUND the next time it runs.');
     console.log(
-      `  Fix: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+      `  Fix: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
     );
     console.log('');
   }
@@ -579,7 +581,7 @@ async function runStatus(options) {
     console.log('  require()s a script under .github/scripts will fail with "module is not');
     console.log('  defined in ES module scope" the next time it runs.');
     console.log(
-      `  Fix: ${buildOverwriteCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
+      `  Fix: ${buildUpdateCommand({ hasTemplates: installedTemplates.length > 0, hasSkill: skillInstalled })}`
     );
     console.log('');
   }
@@ -768,7 +770,7 @@ module.exports = {
     readManifest,
     writeManifest,
     fetchLatestVersion,
-    buildOverwriteCommand,
+    buildUpdateCommand,
     skillPath,
     SKILL_REL_PATH,
     WORKFLOWS,
@@ -776,5 +778,6 @@ module.exports = {
     SCRIPTS,
     SCRIPTS_PACKAGE_JSON,
     REQUIRED_SCRIPT_BY_WORKFLOW,
+    LABELS,
   },
 };