@sabaiway/agent-workflow-kit 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.10.0 — install advice reads the worktree checkout (AD-071)
+
+The install advice picked its package manager from MAIN's `package.json` and lockfiles while the
+printed command targets the SATELLITE (`cd <worktree> && <manager> install`) — so a dirty MAIN
+lockfile could push the advice into ambiguity or the wrong manager, and a MAIN advanced past the
+satellite's base steered a satellite it no longer describes. The evidence and the target are now
+the SAME tree:
+
+- **Manager evidence reads the worktree's own live checkout** — the `packageManager` field and
+  the lockfile scan, the same live lane the dependency-free proof (3.6.0) and the node_modules
+  symlink probe already use. MAIN's mutable working tree never steers manager selection; MAIN
+  state legitimately steers only the symlink lane (the shared-cache link and its unlink-first
+  posture), unchanged.
+- **The contract ships in the worktrees mode doc as one pinned sentence** (a named test locks
+  the exact wording): all manifest/lockfile install evidence is read from the worktree's own
+  live files at the moment the posture is resolved — deliberately NOT «exactly HEAD», because a
+  `post-checkout` hook can shape the checkout before the posture is resolved.
+- **No resume-tolerance smuggling.** The shipped clean-tree `--resume` STOP is pinned byte-exact
+  by a real-git test; dirty-resume semantics remain a queued redesign. A satellite behind an
+  advanced MAIN now gets advice about ITSELF — pinned by a real-git test where MAIN's lockfile
+  advance does not re-steer the satellite's refreshed record.
+- **Honest residual:** a manager signal living only in MAIN's working tree (e.g. an ignored,
+  uncommitted lockfile) no longer steers the advice — the checkout is the truth even when that
+  yields the npm default.
+
 ## 3.9.0 — the --include copy door proves what it copies (AD-070)
 
 Nothing bound the node the provision copy walk read to the node `--include` preflight approved:

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.9.0'
+  version: '3.10.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.9.0",
+  "version": "3.10.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

@@ -104,8 +104,9 @@ PLUS the three facts a fresh satellite session cannot derive from its own checko
   isolated-install command when the package manager is unambiguous, the honest install-by-hand
   advice when it is not, and — when the provisioned `node_modules` is a SYMLINK into main — the
   unlink-first form, because a plain install through the symlink writes into MAIN and is never
-  presented as isolated. When the WORKTREE'S OWN LIVE CHECKOUT is provably dependency-free (its `package.json` declares no dependencies, no `workspaces` field of any shape, no install-lifecycle script, no native-addon manifest, no external workspace manifest beside it — the evidence is what an install run in the satellite would actually read: exactly HEAD at provision time, the satellite's own committed state on `--resume`, never MAIN's mutable working tree) the record and the default-lane report both state `no install needed — the project declares no dependencies` and print no install command. A workspace tree is NEVER provably install-free — a workspace install materializes member links and `.bin` shims even with zero dependencies — and anything else the tool cannot enumerate (an absent or unparseable `package.json`, a malformed dependency or scripts field, an install-lifecycle script — dependency-free is not install-free) leaves the posture UNKNOWN and keeps the existing advice: a false "nothing to install" is worse than a redundant hint. `--install` remains an EXPLICIT request and is always answered with the
+  presented as isolated. When the WORKTREE'S OWN LIVE CHECKOUT is provably dependency-free (its `package.json` declares no dependencies, no `workspaces` field of any shape, no install-lifecycle script, no native-addon manifest, no external workspace manifest beside it — the evidence is what an install run in the satellite would actually read: the checkout's LIVE files at the moment the posture is resolved; on `--resume` a dirty tree is then refused by the clean-tree verify, after the record refresh) the record and the default-lane report both state `no install needed — the project declares no dependencies` and print no install command. A workspace tree is NEVER provably install-free — a workspace install materializes member links and `.bin` shims even with zero dependencies — and anything else the tool cannot enumerate (an absent or unparseable `package.json`, a malformed dependency or scripts field, an install-lifecycle script — dependency-free is not install-free) leaves the posture UNKNOWN and keeps the existing advice: a false "nothing to install" is worse than a redundant hint. `--install` remains an EXPLICIT request and is always answered with the
   isolated-install command.
+  All manifest/lockfile install evidence — the dependency-free proof AND the package-manager selection (the `packageManager` field, lockfiles) — is read from the worktree's own LIVE files at the moment the posture is resolved (on `--resume` too, where a dirty tree is then refused by the clean-tree verify); MAIN's mutable working tree never steers manager selection.
 
 **Honesty:** there is NO preview step on the writers — over-warned by design. The tool never
 commits, never pushes, never runs a subscription CLI. Every content read and regular-file copy

package/tools/worktrees.mjs

@@ -1374,8 +1374,10 @@ const LOCKFILE_MANAGERS = Object.freeze([
 const NEUTRAL_INSTALL_ADVICE =
   'install command not printed — package manager is ambiguous or unknown; install dependencies in the worktree by hand';
 
-const resolveInstallAdvice = ({ root, wtRoot, fs }) => {
-  const pkg = readFileNoFollow(fs, join(root, 'package.json'));
+// Advice evidence = the WORKTREE'S OWN LIVE checkout (manifest AND lockfiles): the printed
+// command runs in the satellite, so what main's working tree happens to hold must not steer it.
+const resolveInstallAdvice = ({ wtRoot, fs }) => {
+  const pkg = readFileNoFollow(fs, join(wtRoot, 'package.json'));
   let manager = null;
   let inspectLocks = false;
   if (pkg.absent) {
@@ -1406,7 +1408,7 @@ const resolveInstallAdvice = ({ root, wtRoot, fs }) => {
     for (const [name, candidate] of LOCKFILE_MANAGERS) {
       let st;
       try {
-        st = fs.lstat(join(root, name));
+        st = fs.lstat(join(wtRoot, name));
       } catch (err) {
         if (err?.code === 'ENOENT') continue;
         return { command: null, instruction: NEUTRAL_INSTALL_ADVICE };
@@ -1481,9 +1483,10 @@ const declaresNativeBuild = (fs, dir) => lstatNoFollow(fs.lstat, join(dir, 'bind
 
 // PROVABLY dependency-free, or nothing — read from the WORKTREE'S OWN LIVE CHECKOUT, never from
 // MAIN's mutable working tree: the evidence is what an install run in THIS worktree would actually
-// read. At provision time that is exactly HEAD; on --resume it follows the session's own edits, in
-// both directions (gained dependencies revoke the proof, shed ones grant it) — the same live lane
-// as the node_modules symlink probe. A dirty main manifest must neither grant nor revoke a verdict
+// read, taken at the moment the posture is resolved (a post-checkout hook may already have shaped
+// the checkout; on --resume it follows the session's own edits, in both directions — gained
+// dependencies revoke the proof, shed ones grant it — the same live lane
+// as the node_modules symlink probe). A dirty main manifest must neither grant nor revoke a verdict
 // about content it does not describe. A `workspaces` field of ANY shape
 // is UNKNOWN outright — a workspace install materializes member links and `.bin` shims even with
 // zero dependencies, so a workspace tree is never provably install-free. Everything else the tool
@@ -1512,20 +1515,20 @@ const declaresNoDependencies = ({ wtRoot, fs }) => {
 // an earlier provision left — an install through it writes into MAIN, and the posture must never
 // hide that). Only then may a PROVEN dependency-free checkout short-circuit: a verdict of
 // "nothing to install" must not ride an install instruction.
-const resolveInstallPosture = ({ root, wtRoot, dependencyFree, fs }) => {
+const resolveInstallPosture = ({ wtRoot, dependencyFree, fs }) => {
   const nmPath = join(wtRoot, 'node_modules');
   const nm = lstatNoFollow(fs.lstat, nmPath);
   if (nm !== null && nm.isSymbolicLink()) {
-    const advice = resolveInstallAdvice({ root, wtRoot, fs });
+    const advice = resolveInstallAdvice({ wtRoot, fs });
     const separator = advice.command === null ? ' — ' : ' && ';
     return `the provisioned node_modules is a symlink into MAIN (an install through it writes into MAIN) — for isolation remove it first: rm ${shellQuoteArg(nmPath)}${separator}${advice.instruction}`;
   }
   if (dependencyFree) return NO_DEPENDENCIES_POSTURE;
-  return resolveInstallAdvice({ root, wtRoot, fs }).instruction;
+  return resolveInstallAdvice({ wtRoot, fs }).instruction;
 };
 
 const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyFree, git, fs, report }) => {
-  const install = resolveInstallAdvice({ root, wtRoot, fs });
+  const install = resolveInstallAdvice({ wtRoot, fs });
   if (installFlag) {
     const dst = join(wtRoot, 'node_modules');
     const existing = lstatNoFollow(fs.lstat, dst);
@@ -1866,7 +1869,7 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
       includes: includesRecorded,
       nodeModules: nodeModulesMode,
       vscode: vscodeMode,
-      install: resolveInstallPosture({ root, wtRoot: targetPath, dependencyFree, fs }),
+      install: resolveInstallPosture({ wtRoot: targetPath, dependencyFree, fs }),
       ...orientationFields({ root, slug }),
     },
     fs,