@tekyzinc/gsd-t 3.10.15 → 3.10.16

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.10.16] - 2026-04-15
+
+### Fixed — unattended supervisor launch friction (3 bugs + UX improvements)
+
+**Background**: Users consistently failed to launch unattended sessions due to compounding pre-flight friction: the supervisor spawn targeted the wrong binary, the dirty-tree check refused on benign files, and missing milestone state caused hard refusals. These issues defeated the purpose of "unattended" mode.
+
+### Changed
+- **`bin/gsd-t-unattended-platform.{js,cjs}`** — `spawnSupervisor()` no longer prepends `"unattended"` as a subcommand. `binPath` now points to `bin/gsd-t-unattended.cjs` (the actual supervisor entry) instead of `bin/gsd-t.js` (which has no `unattended` subcommand and printed "Unknown command" on every launch).
+- **`bin/gsd-t-unattended.{js,cjs}`** — dirty worktree check changed from **refuse** to **auto-whitelist**. Non-whitelisted dirty files are automatically added to `.gsd-t/.unattended/config.json` and the supervisor proceeds. Only genuine git errors (not a repo, etc.) still refuse. Import of `saveConfig` added.
+- **`bin/gsd-t-unattended-safety.{js,cjs}`** — added `saveConfig(projectDir, config)` function to persist auto-whitelisted entries back to the config file. Exported for use by supervisor and tests.
+- **`bin/gsd-t.js`** `updateSingleProject()` — now calls `ensureUnattendedConfig()` (creates `.gsd-t/.unattended/config.json` with all defaults) and `ensureUnattendedGitignore()` (adds `bin/*.cjs`, `.gsd-t/.archive-migration-v1`, `.gsd-t/.task-counter-retired-v1` to `.gitignore`).
+- **`commands/gsd-t-unattended.md`** — Step 1c.1 "Readiness Bootstrap": if no active milestone found, auto-bootstraps from conversation context or `--milestone=` flag instead of refusing. Works from any workflow state. Step 2 dry-run display and binPath updated to reference `gsd-t-unattended.cjs`.
+- **`.gsd-t/contracts/unattended-supervisor-contract.md`** — spawn snippet and exit code 8 description updated.
+- **Tests**: `test/unattended-platform.test.js` shim updated (argv[2] not argv[3]). `test/unattended-supervisor.test.js` dirty-tree test now verifies auto-whitelist behavior + git-error refusal. 1136/1136 tests pass.
+
 ## [3.10.15] - 2026-04-15
 
 ### Fixed — bin tools not propagated to downstream projects (unattended launch fails)

package/bin/gsd-t-unattended-platform.cjs

@@ -178,8 +178,8 @@ function spawnWorker(projectDir, timeoutMs, opts = {}) {
  * state file, and relays `claude -p` workers until the milestone terminates.
  *
  * Spawn recipe:
- *   - `node {binPath} unattended {...args}` — the `unattended` subcommand is
- *     prepended automatically so callers pass only user-facing args.
+ *   - `node {binPath} {...args}` — binPath should be the absolute path to
+ *     `bin/gsd-t-unattended.cjs` (the supervisor entry point), NOT gsd-t.js.
  *   - `detached: true` — the child becomes a process-group leader on POSIX
  *     (darwin/linux) so it survives the parent closing its terminal. On win32
  *     the equivalent flag produces a separate process tree.
@@ -194,13 +194,13 @@ function spawnWorker(projectDir, timeoutMs, opts = {}) {
  *     `docs/unattended-windows-caveats.md` (Task 3).
  *
  * @param {object} params
- * @param {string} params.binPath  Absolute path to `bin/gsd-t.js`.
- * @param {string[]} params.args   Extra args appended after `unattended`.
+ * @param {string} params.binPath  Absolute path to `bin/gsd-t-unattended.cjs`.
+ * @param {string[]} params.args   CLI args passed directly to the supervisor.
  * @param {string} params.cwd      Project directory (supervisor's cwd).
  * @returns {{ pid: number }}      The detached child's PID.
  */
 function spawnSupervisor({ binPath, args, cwd }) {
-  const spawnArgs = [binPath, "unattended", ...(args || [])];
+  const spawnArgs = [binPath, ...(args || [])];
   const opts = {
     cwd,
     detached: true,

package/bin/gsd-t-unattended-platform.js

@@ -178,8 +178,8 @@ function spawnWorker(projectDir, timeoutMs, opts = {}) {
  * state file, and relays `claude -p` workers until the milestone terminates.
  *
  * Spawn recipe:
- *   - `node {binPath} unattended {...args}` — the `unattended` subcommand is
- *     prepended automatically so callers pass only user-facing args.
+ *   - `node {binPath} {...args}` — binPath should be the absolute path to
+ *     `bin/gsd-t-unattended.cjs` (the supervisor entry point), NOT gsd-t.js.
  *   - `detached: true` — the child becomes a process-group leader on POSIX
  *     (darwin/linux) so it survives the parent closing its terminal. On win32
  *     the equivalent flag produces a separate process tree.
@@ -194,13 +194,13 @@ function spawnWorker(projectDir, timeoutMs, opts = {}) {
  *     `docs/unattended-windows-caveats.md` (Task 3).
  *
  * @param {object} params
- * @param {string} params.binPath  Absolute path to `bin/gsd-t.js`.
- * @param {string[]} params.args   Extra args appended after `unattended`.
+ * @param {string} params.binPath  Absolute path to `bin/gsd-t-unattended.cjs`.
+ * @param {string[]} params.args   CLI args passed directly to the supervisor.
  * @param {string} params.cwd      Project directory (supervisor's cwd).
  * @returns {{ pid: number }}      The detached child's PID.
  */
 function spawnSupervisor({ binPath, args, cwd }) {
-  const spawnArgs = [binPath, "unattended", ...(args || [])];
+  const spawnArgs = [binPath, ...(args || [])];
   const opts = {
     cwd,
     detached: true,

package/bin/gsd-t-unattended-safety.cjs

@@ -151,6 +151,27 @@ function loadConfig(projectDir) {
   return merged;
 }
 
+// ── saveConfig ─────────────────────────────────────────────────────────────
+//
+// Persists the given config object back to `.gsd-t/.unattended/config.json`.
+// Creates the directory if missing. Used by auto-whitelist to remember newly
+// whitelisted dirty-tree entries so subsequent launches don't re-warn.
+
+function saveConfig(projectDir, config) {
+  const configDir = path.join(projectDir, ".gsd-t", ".unattended");
+  const configPath = path.join(configDir, "config.json");
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  const serializable = {};
+  for (const key of Object.keys(DEFAULTS)) {
+    if (config[key] !== undefined) {
+      serializable[key] = config[key];
+    }
+  }
+  fs.writeFileSync(configPath, JSON.stringify(serializable, null, 2) + "\n");
+}
+
 // ── checkGitBranch ──────────────────────────────────────────────────────────
 //
 // Runs `git branch --show-current` in projectDir. An empty result indicates
@@ -745,6 +766,7 @@ function detectBlockerSentinel(runLogTail) {
 module.exports = {
   DEFAULTS,
   loadConfig,
+  saveConfig,
   checkGitBranch,
   checkWorktreeCleanliness,
   checkIterationCap,

package/bin/gsd-t-unattended-safety.js

@@ -151,6 +151,27 @@ function loadConfig(projectDir) {
   return merged;
 }
 
+// ── saveConfig ─────────────────────────────────────────────────────────────
+//
+// Persists the given config object back to `.gsd-t/.unattended/config.json`.
+// Creates the directory if missing. Used by auto-whitelist to remember newly
+// whitelisted dirty-tree entries so subsequent launches don't re-warn.
+
+function saveConfig(projectDir, config) {
+  const configDir = path.join(projectDir, ".gsd-t", ".unattended");
+  const configPath = path.join(configDir, "config.json");
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+  const serializable = {};
+  for (const key of Object.keys(DEFAULTS)) {
+    if (config[key] !== undefined) {
+      serializable[key] = config[key];
+    }
+  }
+  fs.writeFileSync(configPath, JSON.stringify(serializable, null, 2) + "\n");
+}
+
 // ── checkGitBranch ──────────────────────────────────────────────────────────
 //
 // Runs `git branch --show-current` in projectDir. An empty result indicates
@@ -745,6 +766,7 @@ function detectBlockerSentinel(runLogTail) {
 module.exports = {
   DEFAULTS,
   loadConfig,
+  saveConfig,
   checkGitBranch,
   checkWorktreeCleanliness,
   checkIterationCap,

package/bin/gsd-t-unattended.cjs

@@ -35,6 +35,7 @@ const { mapHeadlessExitCode } = require("./gsd-t.js");
 const {
   DEFAULTS: SAFETY_DEFAULTS,
   loadConfig,
+  saveConfig,
   checkGitBranch,
   checkWorktreeCleanliness,
   checkIterationCap,
@@ -493,6 +494,7 @@ function doUnattended(argv, deps) {
     releaseSleep: deps._releaseSleep || releaseSleep,
     notify: deps._notify || notify,
     loadConfig: deps._loadConfig || loadConfig,
+    saveConfig: deps._saveConfig || saveConfig,
   };
 
   // ── Load config (optional .gsd-t/.unattended/config.json) ────────────────
@@ -549,7 +551,23 @@ function doUnattended(argv, deps) {
     };
   }
   const treeRes = fn.checkWorktreeCleanliness(projectDir, config);
-  if (!treeRes.ok) {
+  if (!treeRes.ok && treeRes.dirtyFiles && treeRes.dirtyFiles.length > 0) {
+    // Auto-whitelist: add the dirty files to the config and persist, then
+    // proceed instead of refusing. This keeps unattended launch frictionless.
+    for (const file of treeRes.dirtyFiles) {
+      if (!config.dirtyTreeWhitelist.includes(file)) {
+        config.dirtyTreeWhitelist.push(file);
+      }
+    }
+    try {
+      fn.saveConfig(projectDir, config);
+    } catch (_) { /* best effort — config dir may not exist yet */ }
+    // eslint-disable-next-line no-console
+    console.error(
+      `[gsd-t-unattended] auto-whitelisted ${treeRes.dirtyFiles.length} dirty file(s): ${treeRes.dirtyFiles.slice(0, 5).join(", ")}${treeRes.dirtyFiles.length > 5 ? ", …" : ""}`,
+    );
+  } else if (!treeRes.ok) {
+    // Non-file failure (e.g. git error) — still refuse.
     // eslint-disable-next-line no-console
     console.error(
       `[gsd-t-unattended] preflight-refusal: ${treeRes.reason || "dirty worktree"}`,

package/bin/gsd-t-unattended.js

@@ -35,6 +35,7 @@ const { mapHeadlessExitCode } = require("./gsd-t.js");
 const {
   DEFAULTS: SAFETY_DEFAULTS,
   loadConfig,
+  saveConfig,
   checkGitBranch,
   checkWorktreeCleanliness,
   checkIterationCap,
@@ -493,6 +494,7 @@ function doUnattended(argv, deps) {
     releaseSleep: deps._releaseSleep || releaseSleep,
     notify: deps._notify || notify,
     loadConfig: deps._loadConfig || loadConfig,
+    saveConfig: deps._saveConfig || saveConfig,
   };
 
   // ── Load config (optional .gsd-t/.unattended/config.json) ────────────────
@@ -549,7 +551,23 @@ function doUnattended(argv, deps) {
     };
   }
   const treeRes = fn.checkWorktreeCleanliness(projectDir, config);
-  if (!treeRes.ok) {
+  if (!treeRes.ok && treeRes.dirtyFiles && treeRes.dirtyFiles.length > 0) {
+    // Auto-whitelist: add the dirty files to the config and persist, then
+    // proceed instead of refusing. This keeps unattended launch frictionless.
+    for (const file of treeRes.dirtyFiles) {
+      if (!config.dirtyTreeWhitelist.includes(file)) {
+        config.dirtyTreeWhitelist.push(file);
+      }
+    }
+    try {
+      fn.saveConfig(projectDir, config);
+    } catch (_) { /* best effort — config dir may not exist yet */ }
+    // eslint-disable-next-line no-console
+    console.error(
+      `[gsd-t-unattended] auto-whitelisted ${treeRes.dirtyFiles.length} dirty file(s): ${treeRes.dirtyFiles.slice(0, 5).join(", ")}${treeRes.dirtyFiles.length > 5 ? ", …" : ""}`,
+    );
+  } else if (!treeRes.ok) {
+    // Non-file failure (e.g. git error) — still refuse.
     // eslint-disable-next-line no-console
     console.error(
       `[gsd-t-unattended] preflight-refusal: ${treeRes.reason || "dirty worktree"}`,

package/bin/gsd-t.js

@@ -1964,7 +1964,9 @@ function updateSingleProject(projectDir, counts) {
   const binToolsCopied = copyBinToolsToProject(projectDir, projectName);
   const archiveRan = runProgressArchiveMigration(projectDir, projectName);
   const taskCounterRetired = runTaskCounterRetirementMigration(projectDir, projectName);
-  if (guardAdded || changelogCreated || binToolsCopied || archiveRan || taskCounterRetired) {
+  const unattendedConfigCreated = ensureUnattendedConfig(projectDir, projectName);
+  const gitignoreUpdated = ensureUnattendedGitignore(projectDir, projectName);
+  if (guardAdded || changelogCreated || binToolsCopied || archiveRan || taskCounterRetired || unattendedConfigCreated || gitignoreUpdated) {
     counts.updated++;
   } else {
     info(`${projectName} — already up to date`);
@@ -2104,6 +2106,55 @@ function runTaskCounterRetirementMigration(projectDir, projectName) {
   return true;
 }
 
+function ensureUnattendedConfig(projectDir, projectName) {
+  const configDir = path.join(projectDir, ".gsd-t", ".unattended");
+  const configPath = path.join(configDir, "config.json");
+  if (fs.existsSync(configPath)) return false;
+  if (!fs.existsSync(path.join(projectDir, ".gsd-t"))) return false;
+
+  try {
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    const defaultConfig = {
+      protectedBranches: ["main", "master", "develop", "trunk", "release/*", "hotfix/*"],
+      dirtyTreeWhitelist: [
+        ".gsd-t/heartbeat-*.jsonl",
+        ".gsd-t/.context-meter-state.json",
+        ".gsd-t/events/*.jsonl",
+        ".gsd-t/token-metrics.jsonl",
+        ".gsd-t/token-log.md",
+        ".gsd-t/.unattended/*",
+        ".gsd-t/.handoff/*",
+        ".claude/settings.local.json",
+        ".claude/settings.local.json.bak*",
+      ],
+      maxIterations: 200,
+      hours: 24,
+    };
+    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + "\n");
+    info(`${projectName} — created .gsd-t/.unattended/config.json (edit to customize)`);
+    return true;
+  } catch (e) {
+    warn(`${projectName} — failed to create unattended config: ${e.message}`);
+    return false;
+  }
+}
+
+const UNATTENDED_GITIGNORE_ENTRIES = [
+  "bin/*.cjs",
+  ".gsd-t/.archive-migration-v1",
+  ".gsd-t/.task-counter-retired-v1",
+];
+
+function ensureUnattendedGitignore(projectDir, projectName) {
+  const added = ensureGitignoreEntries(projectDir, UNATTENDED_GITIGNORE_ENTRIES);
+  if (added) {
+    info(`${projectName} — added GSD-T entries to .gitignore`);
+  }
+  return added;
+}
+
 function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing, syncCount) {
   log("");
   heading("Update All Complete");

package/commands/gsd-t-unattended.md

@@ -112,6 +112,37 @@ try {
 "
 ```
 
+### 1c.1: Readiness Bootstrap (auto-complete pending state)
+
+**The unattended command must work from ANY workflow state.** If the user says "run unattended," that is an instruction to proceed — not an invitation to ask more questions. Regardless of where the project is in the GSD-T workflow (mid-discussion, pre-milestone, post-partition, between phases), the unattended supervisor should be able to pick up and continue.
+
+The `/gsd-t-resume` worker already knows how to chain through phases automatically. The only thing the unattended command needs is a milestone label in `progress.md` so the supervisor has a target.
+
+**If `MILESTONE=unknown`** (no active milestone found in progress.md):
+
+1. **Look for a milestone** — check in priority order:
+   a. `$ARGUMENTS` — if `--milestone=LABEL` was passed, use it.
+   b. Conversation context — if the user discussed a milestone, feature, or work goal in this session, extract the milestone label from that discussion.
+   c. `.gsd-t/progress.md` — check for any milestone mentioned anywhere (even if not in the standard "Current Milestone" format, e.g., a Decision Log entry like "created milestone M8").
+   d. `.gsd-t/domains/` — if domains exist, infer the milestone from directory names or scope files.
+
+2. **If a milestone is identifiable**:
+   - Ensure `.gsd-t/progress.md` has a `## Current Milestone` section with the label and status `IN PROGRESS`. If missing, add it.
+   - Run `gsd-t-init` silently to fill in any missing required files (it skips existing files).
+   - Print: `ℹ️  Auto-bootstrapped milestone {LABEL} — supervisor workers will continue from current phase.`
+   - Re-read the milestone label.
+
+3. **If no milestone is identifiable at all**:
+   - Print:
+     ```
+     ❌  No active milestone found and none identifiable from context.
+
+         Specify one explicitly: /user:gsd-t-unattended --milestone=M1
+     ```
+   - **STOP.** Do NOT spawn.
+
+**If `MILESTONE` was found but progress.md shows a pre-execution phase** (e.g., milestone was just created, no partition/plan/domains yet): that's fine — proceed with the spawn. The `/gsd-t-resume` worker will read the current state and advance through partition → plan → execute → ... automatically. The unattended command should never second-guess the resume logic or add pre-conditions beyond "a milestone exists."
+
 ### 1d: Check for Stale Stop Sentinel
 
 If `.gsd-t/.unattended/stop` exists from a previous run, remove it before spawning (per contract §10 — the launch command cleans the stale sentinel):
@@ -230,7 +261,7 @@ If `--dry-run` was specified, print:
 
 ```
 🔎  Dry-run mode — would spawn:
-    node bin/gsd-t.js unattended --hours={hours} --milestone={milestone} --max-iterations={maxIterations}
+    node bin/gsd-t-unattended.cjs --hours={hours} --milestone={milestone} --max-iterations={maxIterations}
     Project: {cwd}
 
     No supervisor launched. Remove --dry-run to proceed.
@@ -250,7 +281,7 @@ const hours = parseInt(process.env.GSD_T_HOURS || '24', 10) || 24;
 const milestone = process.env.GSD_T_MILESTONE || '';
 const maxIterations = parseInt(process.env.GSD_T_MAX_ITERATIONS || '200', 10) || 200;
 
-const binPath = path.resolve(__dirname, 'bin', 'gsd-t.js');
+const binPath = path.resolve(__dirname, 'bin', 'gsd-t-unattended.cjs');
 const cwd = process.cwd();
 
 const extraArgs = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.10.15",
+  "version": "3.10.16",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 61 slash commands with unattended supervisor relay, headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",