@sabaiway/agent-workflow-kit 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.8.0 — cleanup never deletes a node_modules it cannot prove ephemeral (AD-069)
+
+Routine non-abandon `worktrees cleanup` used to delete an ignored user-built `node_modules`
+silently: `node_modules` sat unconditionally in the provision-owned root lists, so real user data
+was treated as removable provision footprint. The ownership call is now made LIVE, at cleanup
+time, from what deleting the node would destroy — never from who created it, and never from the
+handoff record:
+
+- **The gate** classifies the worktree's `node_modules` with one no-follow lstat and (for a
+  symlink) one buffer-form readlink: EPHEMERAL exactly when the raw target bytes equal MAIN's
+  `node_modules` path — a relative or re-encoded target that merely resolves to main stays
+  foreign, and the target's kind is irrelevant. Everything else — directory, file, special node —
+  is FOREIGN. The lane is tracked-first: a tracked path or tracked descendant wins over any
+  ignore rule, and an absent node with a live index entry is never clean-absent.
+- **The one exemption** is the ignored-lane matching symlink (exactly what provision creates):
+  the ignored inventory skips it and plain `git worktree remove` unlinks it — after the gate's
+  verdict is RE-PROVEN, same class same lane, immediately before the irreversible remove. Any
+  change in between, or any probe error at any point, is a fail-closed STOP with no remove call.
+- **Every other state stops surgically**, and the recovery matches the lane and kind: ignored/
+  untracked symlink, file, or special node → the exact single-node `rm`; directory → the
+  recursive form; then re-run cleanup (`--abandon` always named second). A TRACKED
+  `node_modules` never gets an `rm` — land its removal from MAIN instead. Probe errors offer no
+  removal command at all. A clean-absent verdict follows the legacy path unchanged, so landing a
+  tracked `node_modules` removal still converges. `--abandon` behavior is unchanged.
+- The contract sentence ships as the exported `CLEANUP_OWNERSHIP_RULE`, emitted on every
+  ownership STOP and pinned into `references/modes/worktrees.md` by a new doc-parity binding.
+
+Honest residuals, stated in the mode doc: the revalidation→remove window stays open (git performs
+the removal; no door there, deliberately); content that git cannot see — or that appears after
+the inventories inside a reset-restored tracked directory — remains a pre-existing generic
+worktree-removal residual, no longer masked by a false ownership claim; on Windows a strict-bytes
+mismatch degrades to the surgical STOP, never a deletion.
+
 ## 3.7.0 — the worktrees-dir advisor item can finally converge (AD-068)
 
 The `recommendations` advisor's `worktrees-dir` item used to fire forever: its only convergence

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.7.0'
+  version: '3.8.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/worktrees.md

@@ -54,8 +54,23 @@ own verbatim error through the existing Git-error surface.
 - `cleanup <slug> [--branch <name>] [--abandon]` — take the same transient lock and remove a LANDED
   worktree fail-closed after live landed-verification against main HEAD. Verification uses exactly
   the land exclusions (`docs/ai`, `docs/plans`), then checks untracked and ignored content before a
-  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral;
-  `node_modules` of any kind is provision-derivable because provision explicitly advises installs.
+  plain worktree remove, branch `-d`, and prune. Provision-derived ignored containers are ephemeral —
+  except `node_modules`, which is never assumed provision-owned:
+  node_modules ownership is decided live: only a symlink whose raw target bytes equal MAIN's node_modules path, in the ignored lane, is provision-ephemeral; an absent node with no index entry is clean; every other state stops cleanup to protect user data or because inspection failed.
+  The verdict is
+  computed once, after landed verification and before the untracked/ignored inventories (it also
+  catches tracked `node_modules` and empty untracked directories git never lists); the lane is
+  tracked-first (a tracked path or tracked descendant wins over any ignore rule; an absent node with
+  a live index entry is never clean-absent); the single exempt state is re-proven — same class, same
+  lane — immediately before `git worktree remove`, and any deviation or probe error is a fail-closed
+  STOP with no removal performed. STOP recovery is surgical and lane-specific: untracked/ignored
+  symlink, file, or special node → a single-node `rm`; directory → the recursive form; then re-run
+  cleanup — `--abandon` is always named second; a tracked `node_modules` never gets an `rm` (land the
+  removal from MAIN instead); a probe error gets no removal command at all. A clean-absent verdict
+  follows the legacy cleanup path and carries no post-reset ownership proof: git-invisible or ignored
+  content appearing after the inventories, or surviving inside a reset-restored tracked directory,
+  remains a pre-existing generic worktree-removal residual (not `node_modules`-specific). On Windows
+  a strict-bytes mismatch degrades to the surgical STOP — fail-closed friction, never deletion.
   Foreign content stops cleanup. `--abandon` is the ONE destructive arm: it DESTROYS unlanded work,
   requires the handoff identity, and is the only path where `--force` may appear.
 

package/tools/doc-parity.mjs

@@ -34,7 +34,7 @@ import {
 } from './recommendations.mjs';
 import { SKIPPED_READONLY } from './setup-backends.mjs';
 import { LATENT_ARM_NOTICE } from './review-state.mjs';
-import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE } from './worktrees.mjs';
+import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE, CLEANUP_OWNERSHIP_RULE } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -105,6 +105,9 @@ export const BINDINGS = Object.freeze([
   valueBinding('queue-shared-rule', QUEUE_SHARED_RULE, QUEUE_SHARED_RULE, [WORKTREES_DOC]),
   valueBinding('landing-from-main', LANDING_FROM_MAIN, LANDING_FROM_MAIN, [WORKTREES_DOC]),
   valueBinding('no-dependencies-posture', NO_DEPENDENCIES_POSTURE, NO_DEPENDENCIES_POSTURE, [WORKTREES_DOC]),
+  // The cleanup-ownership contract (AD-069): the exact live sentence every ownership STOP emits —
+  // a reworded mode doc dropping the class × lane contract fails this pin plus the gate.
+  valueBinding('cleanup-ownership-rule', CLEANUP_OWNERSHIP_RULE, CLEANUP_OWNERSHIP_RULE, [WORKTREES_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -151,8 +154,9 @@ Usage:
 A CLOSED, exported registry binds each live code constant — the autonomy-doctor contract (the EXIT
 table, the status tokens, the trusted-dir allowlist), the recommendations/upgrade presentation
 contract (section header, empty line, verdict templates), the acks-store path, the setup refresh
-degrade token, the review-state clean-tree latent-arm notice, and the worktrees provision-record
-orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture) — to
+degrade token, the review-state clean-tree latent-arm notice, the worktrees provision-record
+orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture), and
+the worktrees cleanup-ownership rule — to
 the exact token its references/modes/*.md contract must carry, and
 asserts the CURRENT value renders into every bound file. A drifted doc, an unreadable bound file,
 or an absent token FAILS CLOSED.

package/tools/worktrees.mjs

@@ -937,6 +937,10 @@ export const NO_DEPENDENCIES_POSTURE = 'no install needed — the project declar
 // The recorded node_modules mode for that same verdict: provision neither advised nor created a
 // node_modules for this worktree.
 export const NODE_MODULES_NONE = 'no-dependencies';
+// The cleanup-ownership contract (AD-069): ownership is information content, decided live at
+// cleanup time — never provenance, never the handoff record. Doc-parity pins this exact sentence
+// into the worktrees mode doc; every ownership STOP emits it.
+export const CLEANUP_OWNERSHIP_RULE = "node_modules ownership is decided live: only a symlink whose raw target bytes equal MAIN's node_modules path, in the ignored lane, is provision-ephemeral; an absent node with no index entry is clean; every other state stops cleanup to protect user data or because inspection failed";
 
 // The record is LINE-oriented and is parsed back for IDENTITY, so a value carrying a control byte
 // is refused rather than written: a newline spills a second line the parser reads as a real field
@@ -2266,7 +2270,6 @@ const provisionKnownRoots = (identity) => {
     ...registryRoots(),
     ...identity.record.includes.map(safeRecordedPath),
     PLANS_REL,
-    'node_modules',
   ];
   if (identity.record.vscode === 'written') roots.push('.vscode/settings.json');
   return [...new Set(roots)];
@@ -2277,7 +2280,6 @@ const provisionKnownDirectoryRoots = ({ root, identity, fs }) => {
     ...KIT_OWN_PATHS.filter(isDirPattern),
     ...KNOWN_FOOTPRINT.filter((entry) => entry.type === 'dir').map((entry) => entry.pattern),
     PLANS_REL,
-    'node_modules',
   ].map((path) => normalizeSlashes(path).replace(/^\//, '').replace(/\/$/, ''));
   for (const include of identity.record.includes.map(safeRecordedPath)) {
     const kind = classifyNodeNoFollow(join(root, include), fs).kind;
@@ -2294,7 +2296,7 @@ const rootCoveringPath = (path, roots) => roots.find((root) => {
   return path === root || path.startsWith(`${root}/`);
 }) ?? null;
 
-const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
+const foreignIgnoredPaths = ({ root, git, identity, fs, exemptNodeModules = false }) => {
   const result = gitRead(
     git, ['status', '--porcelain=v1', '-z', '--ignored', '--untracked-files=all'], root,
     'git status --ignored failed',
@@ -2305,6 +2307,9 @@ const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
     for (const rawPath of entry.paths) {
       const normalized = normalizeSlashes(rawPath);
       const path = normalized.replace(/\/$/, '');
+      // The ONE ownership exemption (AD-069): the gate has already proven this exact node an
+      // ignored-lane matching symlink; it is neither re-probed nor reported here.
+      if (exemptNodeModules && path === NODE_MODULES_REL) continue;
       const kind = classifyNodeNoFollow(join(root, path), fs).kind;
       const rootType = kind === 'plain-directory' || kind === 'symlink-to-directory'
         ? 'directory'
@@ -2327,6 +2332,88 @@ const foreignIgnoredPaths = ({ root, git, identity, fs }) => {
   }).map(([path]) => path);
 };
 
+// ── the node_modules ownership gate (AD-069) ──────────────────────────────────────────────
+// Class {absent, ephemeral, foreign} × lane {tracked, ignored, untracked}, decided live from
+// exactly one no-follow lstat + (symlink only) one buffer-form readlink + the git lane probes.
+// The record is never consulted; every probe error is FOREIGN fail-closed with no recovery
+// command. The single exempt state — the ignored-lane matching link — is re-proven immediately
+// before the irreversible worktree remove.
+
+const NODE_MODULES_REL = 'node_modules';
+
+const nodeModulesInspectStop = (nmPath, detail) => stop(
+  `cleanup stopped: cannot inspect ${nmPath} (${detail})\n${CLEANUP_OWNERSHIP_RULE}`,
+);
+
+const nodeModulesSnapshot = ({ wtRoot, mainRoot, git, fs }) => {
+  const nmPath = join(wtRoot, NODE_MODULES_REL);
+  const node = (() => {
+    try {
+      return { stat: fs.lstat(nmPath) };
+    } catch (error) {
+      return error?.code === 'ENOENT' ? { stat: null } : { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (node.error) throw nodeModulesInspectStop(nmPath, node.error);
+  const trackedProbe = git(['ls-files', '--cached', '-z', '--', NODE_MODULES_REL], wtRoot);
+  if (trackedProbe.status !== 0) {
+    throw nodeModulesInspectStop(nmPath, `git ls-files failed: ${(trackedProbe.stderr || trackedProbe.stdout).trim()}`);
+  }
+  const tracked = trackedProbe.stdout.length > 0;
+  if (node.stat === null) {
+    return { klass: 'absent', kind: 'absent', lane: tracked ? 'tracked' : null, nmPath };
+  }
+  const lane = tracked ? 'tracked' : (() => {
+    const probe = git(['check-ignore', '--', NODE_MODULES_REL], wtRoot);
+    if (probe.status === 0) return 'ignored';
+    if (probe.status === 1) return 'untracked';
+    throw nodeModulesInspectStop(nmPath, `git check-ignore failed: ${(probe.stderr || probe.stdout).trim()}`);
+  })();
+  if (!node.stat.isSymbolicLink()) {
+    const kind = node.stat.isDirectory() ? 'directory' : node.stat.isFile() ? 'file' : 'special';
+    return { klass: 'foreign', kind, lane, nmPath };
+  }
+  const target = (() => {
+    try {
+      return { bytes: fs.readlink(nmPath, { encoding: 'buffer' }) };
+    } catch (error) {
+      return { error: error?.code ?? 'fs error' };
+    }
+  })();
+  if (target.error) throw nodeModulesInspectStop(nmPath, target.error);
+  // Raw BYTES against MAIN's node_modules path — never decoded, never resolved: a relative or
+  // re-encoded form that merely RESOLVES to main stays foreign, and the target's kind is
+  // irrelevant (unlink touches only the link).
+  const matches = Buffer.compare(target.bytes, Buffer.from(join(mainRoot, NODE_MODULES_REL))) === 0;
+  return { klass: matches ? 'ephemeral' : 'foreign', kind: 'symlink', lane, nmPath };
+};
+
+const nodeModulesExemptVerdict = (snapshot) => snapshot.klass === 'ephemeral' && snapshot.lane === 'ignored';
+
+const composeNodeModulesStop = ({ snapshot, slug, branch, changed = false }) => {
+  const { klass, kind, lane, nmPath } = snapshot;
+  const kindDesc = kind === 'symlink'
+    ? (klass === 'ephemeral' ? 'a main-matching symlink' : 'a foreign symlink')
+    : kind === 'directory' ? 'a directory'
+      : kind === 'file' ? 'a regular file'
+        : kind === 'special' ? 'a special node' : 'absent';
+  const head = `cleanup stopped: ${nmPath} is ${kindDesc} in the ${lane} lane`
+    + `${changed ? ' (changed during cleanup)' : ''}\n${CLEANUP_OWNERSHIP_RULE}`;
+  if (lane === 'tracked') {
+    return stop([
+      head,
+      'this node_modules is tracked: removing it by hand only creates drift that stops cleanup earlier — land its removal from MAIN, then re-run cleanup',
+      destructiveRecovery({ slug, branch }),
+    ].join('\n'));
+  }
+  const removal = kind === 'directory' ? `rm -rf -- ${shellQuoteArg(nmPath)}` : `rm -- ${shellQuoteArg(nmPath)}`;
+  return stop([
+    head,
+    `remove it yourself, then re-run cleanup: ${removal}`,
+    destructiveRecovery({ slug, branch }),
+  ].join('\n'));
+};
+
 const composeCleanupCommand = ({ slug, branch, abandon }) =>
   `cleanup ${shellQuoteArg(slug)}` +
   `${branch === `${DEFAULT_BRANCH_PREFIX}${slug}` ? '' : ` --branch ${shellQuoteArg(branch)}`}` +
@@ -2380,6 +2467,7 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
 
     const knownRoots = provisionKnownRoots(identity);
     let removalRoots = [];
+    let nodeModulesExempt = false;
     if (!flags.abandon) {
       const mainHead = gitRead(git, ['rev-parse', 'HEAD'], root, 'cannot resolve main HEAD').stdout.trim();
       // Transfer verification excludes docs/ai and docs/plans; their tracked drift is checked separately before reset.
@@ -2422,6 +2510,16 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
         );
       }
 
+      // The ownership gate (AD-069) runs BEFORE the inventories: it also catches tracked
+      // node_modules and empty untracked directories git never lists. Clean-absent proceeds on
+      // the legacy path with no post-reset ownership arm; the single exemption is re-proven
+      // below, immediately before the irreversible remove.
+      const ownership = nodeModulesSnapshot({ wtRoot: entry.path, mainRoot: root, git, fs });
+      if (!nodeModulesExemptVerdict(ownership) && !(ownership.klass === 'absent' && ownership.lane !== 'tracked')) {
+        throw composeNodeModulesStop({ snapshot: ownership, slug, branch });
+      }
+      nodeModulesExempt = nodeModulesExemptVerdict(ownership);
+
       const untracked = untrackedPaths(git, entry.path);
       const foreign = [];
       for (const path of untracked) {
@@ -2435,7 +2533,7 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
           destructiveRecovery({ slug, branch }),
         );
       }
-      const foreignIgnored = foreignIgnoredPaths({ root: entry.path, git, identity, fs });
+      const foreignIgnored = foreignIgnoredPaths({ root: entry.path, git, identity, fs, exemptNodeModules: nodeModulesExempt });
       if (foreignIgnored.length > 0) {
         throw stop(`foreign ignored content requires --abandon:\n${foreignIgnored.join('\n')}`);
       }
@@ -2455,6 +2553,20 @@ export const runCleanup = ({ argvSlug, flags, cwd, git, deps, log }) => {
       for (const rel of removalRoots) {
         removeNodeNoFollow({ root: entry.path, abs: join(entry.path, rel), fs, label: rel });
       }
+      if (nodeModulesExempt) {
+        // The authoritative re-proof (AD-069): the verdict authorizing the irreversible remove
+        // postdates the last tree-mutating operation. Strict equality with the exempt state —
+        // never re-authorization: ANY deviation fails closed with no remove call.
+        const revalidated = nodeModulesSnapshot({ wtRoot: entry.path, mainRoot: root, git, fs });
+        if (!nodeModulesExemptVerdict(revalidated)) {
+          if (revalidated.klass === 'absent' && revalidated.lane !== 'tracked') {
+            throw stop(
+              `cleanup stopped: ${revalidated.nmPath} changed during cleanup (now absent) — re-run cleanup\n${CLEANUP_OWNERSHIP_RULE}`,
+            );
+          }
+          throw composeNodeModulesStop({ snapshot: revalidated, slug, branch, changed: true });
+        }
+      }
     }
 
     removeWorktree({ root, entry, branch, abandon: flags.abandon, git });