worclaude 2.10.0 → 2.10.2

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.10.2] — 2026-04-30
+
+Bundles a dogfood catch-up of this repo's own `.claude/` (skipping from v2.8.0 to v2.10.1 in one upgrade run) with a real scaffold bug fix surfaced during that upgrade — `.claude/workflow-ref/` (transient upgrade-time conflict references) was missing from the scaffolder's `updateGitignore` entries, so every user running `worclaude upgrade` had those files pollute their git status. Also closes the BACKLOG "claude --worktree command visibility" item via a docs-only fix: investigation confirmed Claude Code does not create a "minimal `.claude/`" (the worktree's `.claude/` is a normal git checkout from `origin/HEAD`); the perceived missing-commands symptom was caused by main lagging develop, and the existing `subagent-usage` skill already documented the mechanism. The gap was direct `claude --worktree` users with no agent-mediated freshness preamble — filled with a one-paragraph copy-paste reset block.
+
+### Fixed
+
+- **`.claude/workflow-ref/` now scaffolded into `.gitignore`** (PR #174) — `src/core/scaffolder.js` `updateGitignore` entries list now includes `.claude/workflow-ref/`. Existing users pick up the fix on the next scaffold or upgrade pass that runs `updateGitignore`. Two existing tests updated (`is idempotent` seed input + `writes exactly N entries` count 10 → 11 + expected array).
+
+### Docs
+
+- **Manual freshness reset for direct `claude --worktree`** (PR #175) — added a copy-paste workaround block (`cd .claude/worktrees/<name> && git fetch origin && git reset --hard origin/<your-branch>`) to the existing "Base-branch gotcha" section of the `subagent-usage` skill, in both `templates/skills/universal/subagent-usage.md` and the dogfood mirror. Closes BACKLOG "claude --worktree command visibility" (the entry's "minimal `.claude/`" framing was wrong; investigation captured in the session summary).
+
+### Internal
+
+- **Dogfood catch-up v2.8.0 → v2.10.1** (PR #174) — applied 3 release groups' worth of template evolution to this repo's own `.claude/`: sandbox.network block in settings.json (self-testing the v2.10.1 feature), observability hooks for UserPromptSubmit / InstructionsLoaded / SubagentStart / SubagentStop, 3 obs-\*.cjs hook scripts, 3 helper scripts under `.claude/scripts/`, and template-current versions of 5 slash commands plus the git-conventions skill that had drifted behind their templates.
+
+Release group: 2 PRs (1 patch, 1 none). v2.10.1 → v2.10.2.
+
+## [2.10.1] — 2026-04-29
+
+Adds opt-in scaffolding for Claude Code 2.1.113's `sandbox.network` deny/allow lists. Worclaude is a scaffolder, so the new `templates/settings/base.json` ships empty `deniedDomains` and `allowedDomains` stubs rather than an opinionated default list — project owners decide their own network policy. The merge paths for both fresh init (Scenario A) and existing-project init/upgrade (Scenarios B/C) union-merge the new arrays preserving any user-added domains, and a new `worclaude doctor` check warns when the block is missing or malformed (with `worclaude upgrade` as the remediation hint). Also bundles a Dependabot major bump to `commander` 14, which is now Node-20+-only and was unblocked by the v2.10.0 Node 18 drop.
+
+### Added
+
+- **Sandbox network scaffolding** (PR #172) — `templates/settings/base.json` now scaffolds `sandbox.network.deniedDomains: []` and `allowedDomains: []` between the existing `permissions` and `hooks` blocks. New `mergeSettings` helper `unionStringList(inputs, accessor)` in `src/core/scaffolder.js` handles both `permissions.allow` and the new sandbox arrays uniformly. Backward compatible: a base without `sandbox` produces output without `sandbox`, so legacy callers in tests or downstream consumers don't surface the key spuriously.
+- **`appendUnique(target, key, source)` helper** in `src/core/merger.js` (PR #172) — folds three previously-duplicated union-merge call sites in `mergeSettingsPermissionsAndHooks` (allow / deny / sandbox-arrays) into one-liners. Extracted during a `/simplify` pass after three parallel review agents flagged the duplication.
+- **`checkSandboxBlock` doctor check** (PR #172) — warns when `settings.json` is missing the `sandbox` block (with a `worclaude upgrade` remediation pointer for legacy installs), when `sandbox.network` is malformed, or when either array isn't actually an array.
+
+### Changed
+
+- **`commander` 13.1.0 → 14.0.3** (PR #171) — Dependabot major bump. Commander 14 requires Node 20+ (already satisfied after v2.10.0's Node 18 drop) and adds `helpGroup`/`optionsGroup`/`commandsGroup` APIs plus unescaped negative-number support. Worclaude's CLI surface is unaffected.
+- ⚠ **PR #171 shipped without a `Version bump:` declaration** — Dependabot-generated body, no manual annotation. Treated as `none` per `/sync`'s "missing → none" rule and surfaced here permanently. PR #172's `patch` declaration drove the release.
+
+### Tests
+
+- 967 → 992 (+25 net). Per-stack sandbox-array assertions across all 16 supported language templates (replaced one all-stacks loop test for individual failure attribution); 3 scaffolder unit tests covering union-merge, dedup, and legacy-passthrough; 2 Scenario B regressions for legacy-install upgrade and user-domain preservation through subsequent merges; 2 doctor checks for missing-block (legacy install) and malformed-block scenarios.
+
+Release group: 2 PRs (1 patch, 1 missing-declaration treated as none). v2.10.0 → v2.10.1.
+
 ## [2.10.0] — 2026-04-29
 
 Drops support for Node 18, which reached LTS end-of-life on 2025-04-30 (12 months before this release). The drop unblocks two Dependabot PRs stuck on Node-20-only features (`inquirer 13`'s `util.styleText` and `ora 9`'s regex `v` flag) and ships those bumps in the same release. Also recovers from a Dependabot routing misconfiguration: `.github/dependabot.yml` now declares `target-branch: develop` for both ecosystems, fixing a config gap that caused 5 PRs in the v2.9.3 → v2.10.0 window to be opened against main instead of develop. Their content is preserved across both branches via a recovery sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.10.0",
+  "version": "2.10.2",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -66,7 +66,7 @@
   "dependencies": {
     "@sefaertunc/anthropic-watch-client": "^1.0.2",
     "chalk": "^5.4.1",
-    "commander": "^13.1.0",
+    "commander": "^14.0.3",
     "fs-extra": "^11.3.0",
     "inquirer": "^13.4.2",
     "ora": "^9.4.0",

package/src/commands/doctor.js

@@ -286,6 +286,36 @@ async function readSettingsJson(projectRoot) {
   }
 }
 
+async function checkSandboxBlock(projectRoot) {
+  const settings = await readSettingsJson(projectRoot);
+  if (!settings) return null;
+
+  if (!settings.sandbox) {
+    return result(
+      WARN,
+      'Sandbox block',
+      'settings.json missing `sandbox` block. Run `worclaude upgrade` to scaffold network deny/allow lists.'
+    );
+  }
+
+  const network = settings.sandbox.network;
+  if (!network || typeof network !== 'object') {
+    return result(WARN, 'Sandbox block', '`sandbox.network` block missing or malformed');
+  }
+
+  const issues = [];
+  if (!Array.isArray(network.deniedDomains)) {
+    issues.push('`deniedDomains` not an array');
+  }
+  if (!Array.isArray(network.allowedDomains)) {
+    issues.push('`allowedDomains` not an array');
+  }
+  if (issues.length > 0) {
+    return result(WARN, 'Sandbox block', issues.join('; '));
+  }
+  return result(PASS, 'Sandbox block', null);
+}
+
 async function checkHookEventNames(projectRoot) {
   const settings = await readSettingsJson(projectRoot);
   if (!settings) {
@@ -1047,6 +1077,7 @@ export async function doctorCommand(options = {}) {
   record('core', await checkClaudeMdMemoryGuidance(projectRoot));
   record('core', await checkAgentsMd(projectRoot));
   record('core', await checkSettingsJson(projectRoot));
+  record('core', await checkSandboxBlock(projectRoot));
   record('core', await checkSessions(projectRoot));
   spacer();
 

package/src/core/merger.js

@@ -241,20 +241,28 @@ export async function mergeSettingsPermissionsAndHooks(
   const existing = parseUserJson(existingRaw, '.claude/settings.json');
 
   // Merge permissions (Tier 1) — union-merge both allow and deny
-  const existingAllow = existing.permissions?.allow || [];
-  const workflowAllow = workflowSettings.permissions?.allow || [];
-  const newAllow = workflowAllow.filter((p) => !existingAllow.includes(p));
   if (!existing.permissions) existing.permissions = {};
-  existing.permissions.allow = [...existingAllow, ...newAllow];
+  const newAllow = appendUnique(existing.permissions, 'allow', workflowSettings.permissions?.allow);
 
-  const existingDeny = existing.permissions?.deny || [];
-  const workflowDeny = workflowSettings.permissions?.deny || [];
-  const newDeny = workflowDeny.filter((p) => !existingDeny.includes(p));
-  if (newDeny.length > 0 || existingDeny.length > 0) {
-    existing.permissions.deny = [...existingDeny, ...newDeny];
+  const existingDenyLen = (existing.permissions.deny ?? []).length;
+  const newDeny = appendUnique(existing.permissions, 'deny', workflowSettings.permissions?.deny);
+  if (existingDenyLen === 0 && newDeny === 0) {
+    delete existing.permissions.deny;
   }
 
-  report.added.permissions = newAllow.length + newDeny.length;
+  report.added.permissions = newAllow + newDeny;
+
+  // Merge sandbox block (Tier 1 — additive, preserves user customizations)
+  const workflowSandbox = workflowSettings.sandbox?.network;
+  if (workflowSandbox) {
+    if (!existing.sandbox) existing.sandbox = {};
+    if (!existing.sandbox.network || typeof existing.sandbox.network !== 'object') {
+      existing.sandbox.network = {};
+    }
+    for (const key of ['deniedDomains', 'allowedDomains']) {
+      appendUnique(existing.sandbox.network, key, workflowSandbox[key]);
+    }
+  }
 
   // Merge hooks (Tier 1 + Tier 3)
   if (!existing.hooks) existing.hooks = {};
@@ -360,6 +368,13 @@ async function mergeSettingsJson(projectRoot, existingScan, selections, report)
   }
 }
 
+function appendUnique(target, key, source) {
+  const existing = Array.isArray(target[key]) ? target[key] : [];
+  const additions = Array.isArray(source) ? source.filter((d) => !existing.includes(d)) : [];
+  target[key] = [...existing, ...additions];
+  return additions.length;
+}
+
 function countHooks(hooks) {
   if (!hooks) return 0;
   return Object.values(hooks).reduce((sum, entries) => sum + entries.length, 0);

package/src/core/scaffolder.js

@@ -78,6 +78,7 @@ export async function updateGitignore(projectDir) {
     '.claude/cache/',
     '.claude/scratch/',
     '.claude/observability/',
+    '.claude/workflow-ref/',
   ];
   const header = '# Worclaude (generated workflow files)';
 
@@ -204,16 +205,31 @@ export async function scaffoldMemoryDocs(projectRoot) {
 
 export function mergeSettings(base, ...stacks) {
   const merged = JSON.parse(JSON.stringify(base));
-  const baseAllow = merged.permissions?.allow || [];
+  const inputs = [base, ...stacks].filter(Boolean);
 
-  for (const stack of stacks) {
-    if (!stack) continue;
-    const stackAllow = stack.permissions?.allow || [];
-    if (stackAllow.length > 0) {
-      baseAllow.push(...stackAllow);
-    }
+  merged.permissions.allow = unionStringList(inputs, (i) => i.permissions?.allow);
+
+  if (merged.sandbox?.network) {
+    merged.sandbox.network.deniedDomains = unionStringList(
+      inputs,
+      (i) => i.sandbox?.network?.deniedDomains
+    );
+    merged.sandbox.network.allowedDomains = unionStringList(
+      inputs,
+      (i) => i.sandbox?.network?.allowedDomains
+    );
   }
 
-  merged.permissions.allow = [...new Set(baseAllow)];
   return merged;
 }
+
+function unionStringList(inputs, accessor) {
+  const set = new Set();
+  for (const input of inputs) {
+    const list = accessor(input);
+    if (Array.isArray(list)) {
+      for (const item of list) set.add(item);
+    }
+  }
+  return [...set];
+}

package/templates/settings/base.json

@@ -81,6 +81,12 @@
       "Bash(rm -rf $HOME)", "Bash(rm -rf $HOME/*)"
     ]
   },
+  "sandbox": {
+    "network": {
+      "deniedDomains": [],
+      "allowedDomains": []
+    }
+  },
   "hooks": {
     "PostToolUse": [
       {

package/templates/skills/universal/subagent-usage.md

@@ -88,6 +88,14 @@ Run `worclaude doctor` to diagnose. Fix locally with `git remote set-head origin
 their worktree to match the parent's current branch automatically; other worktree
 agents do not.
 
+If you invoke `claude --worktree` directly (not via an agent), no preamble runs
+— sync the worktree manually before doing real work:
+
+```bash
+cd .claude/worktrees/<name>
+git fetch origin && git reset --hard origin/<your-working-branch>
+```
+
 Benefits:
 - Agent's changes don't conflict with your uncommitted work
 - You can review agent changes before merging