@sabaiway/agent-workflow-kit 3.5.0 → 3.6.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.6.0 — the dependency-free install posture: a proof, never a default (AD-067)
+
+On a provably dependency-free project the provision record and the default-lane report no longer
+print a generic `npm install` hint: both state
+`no install needed — the project declares no dependencies` (recorded node_modules mode
+`no-dependencies`), and a `doc-parity` binding pins the posture string to the mode doc.
+
+The verdict is a PROOF granted only on evidence the tool actually read — the WORKTREE'S OWN LIVE
+checkout: what an install run there would actually read, exactly HEAD at provision time and the
+satellite's own committed state on `--resume`, never MAIN's mutable working tree (which can
+diverge from what the satellite actually holds; real-git tests pin both refresh directions).
+Everything the tool cannot vouch for leaves the posture UNKNOWN with the honest advice kept — the
+fail-safe direction, because a false "nothing to install" is worse than a redundant hint:
+
+- a `workspaces` field of ANY shape, outright — a workspace install materializes member links and
+  `.bin` shims even with zero dependencies, so a workspace tree is never provably install-free;
+- an external workspace manifest beside the root (`pnpm-workspace.yaml`/`.yml`, `lerna.json`);
+- a malformed manifest, dependency field, or `scripts` shape (three-valued verdicts — malformed is
+  `unknown`, never "none"; a lifecycle key with a non-string value fails closed);
+- an install-lifecycle script — dependency-free is NOT install-free: the CLOSED, test-pinned set
+  is the npm lifecycle (including the deprecated `prepublish`) plus `pnpm:devPreinstall`; a
+  native-addon manifest (`binding.gyp`) is a mandatory install too.
+
+The posture COMPOSES with the shipped record contract, and LIVE STATE WINS: a node already at the
+worktree — a directory, or a symlink left by an earlier provision, even dangling — records
+`present` before any MAIN-state early return, the AD-065 symlink unlink-first arm is untouched for
+every non-proven project, and `--install` remains an explicit request that is always answered with
+the isolated-install command while the record still states the posture.
+
+Third safe slice of the deferred parallel-track work (AD-063); node_modules ownership and
+resume-verify semantics stay separate redesigns.
+
 ## 3.5.0 — the provision record orients a fresh satellite session (AD-065)
 
 The worktrees provision record was an identity stub; a fresh satellite session could not derive

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

package/capability.json

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

package/package.json

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

@@ -70,7 +70,7 @@ 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. `--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: 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
   isolated-install command.
 
 **Honesty:** there is NO preview step on the writers — over-warned by design. The tool never

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 } from './worktrees.mjs';
+import { QUEUE_SHARED_RULE, LANDING_FROM_MAIN, NO_DEPENDENCIES_POSTURE } from './worktrees.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -99,10 +99,12 @@ export const BINDINGS = Object.freeze([
   // actually emits — a reworded doc dropping the notice fails this pin plus the gate.
   valueBinding('latent-arm-notice', LATENT_ARM_NOTICE, LATENT_ARM_NOTICE, [REVIEW_STATE_DOC]),
   // The provision-record orientation contract (same "the tool knows and does not say" class): the
-  // shared-queue rule and the landing-from-main fact were prose-only bars a doc could silently
-  // drop, so both are pinned to the live strings the record actually carries.
+  // shared-queue rule, the landing-from-main fact, and the no-dependencies install posture were
+  // prose-only bars a doc could silently drop, so all are pinned to the live strings the record
+  // actually carries.
   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]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────
@@ -150,8 +152,8 @@ A CLOSED, exported registry binds each live code constant — the autonomy-docto
 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) — to the exact token its
-references/modes/*.md contract must carry, and
+orientation contract (shared-queue rule, landing-from-main, no-dependencies install posture) — 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

@@ -933,6 +933,10 @@ export const QUEUE_BASENAME = 'queue.md';
 export const QUEUE_SHARED_RULE =
   'the series index is SHARED and lives ONLY in main: read it at the absolute path above, and never copy it into this worktree, because docs/plans is git-ignored and machine-local, so a copy silently diverges from what main and every other worktree are writing. This worktree never WRITES that file: reaching outside it is an fs_outside_repo action the autonomy policy denies by default. Put new findings in THIS handoff record instead — it is the channel that survives the landing, and main appends them to the index from here';
 export const LANDING_FROM_MAIN = 'landing runs FROM MAIN, never from this worktree';
+export const NO_DEPENDENCIES_POSTURE = 'no install needed — the project declares no dependencies';
+// 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 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
@@ -1250,21 +1254,110 @@ const resolveInstallAdvice = ({ root, wtRoot, fs }) => {
   return { command, instruction: command };
 };
 
+// Exported and frozen so the closed sets are test-pinned in BOTH directions (a member can neither
+// be dropped nor smuggled in without failing the pin).
+export const DEPENDENCY_FIELDS = Object.freeze(['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']);
+// Workspace declarations this tool cannot read. Their presence makes the dependency inventory
+// unknowable from package.json alone, so it is never proof.
+export const EXTERNAL_WORKSPACE_MANIFESTS = Object.freeze(['pnpm-workspace.yaml', 'pnpm-workspace.yml', 'lerna.json']);
+
+const readPackageJson = (fs, path) => {
+  const file = readFileNoFollow(fs, path);
+  if (!file.bytes) return null;
+  try {
+    const parsed = JSON.parse(String(file.bytes));
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+// A dependency field is read THREE ways, never two: 'has' (a non-empty plain object), 'none' (the
+// field is absent, or an empty plain object), and 'unknown' for every other shape — a string, an
+// array, null. A malformed manifest is evidence of NOTHING, so it must never read as "none".
+const dependencyFieldsVerdict = (pkg) => {
+  let verdict = 'none';
+  for (const field of DEPENDENCY_FIELDS) {
+    if (!Object.hasOwn(pkg, field)) continue;
+    const value = pkg[field];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return 'unknown';
+    if (Object.keys(value).length > 0) verdict = 'has';
+  }
+  return verdict;
+};
+
+// A project with NO declared dependencies can still REQUIRE an install: a package-manager install
+// runs the WHOLE install-lifecycle set — the npm set (including the deprecated `prepublish`, which
+// historically fired on install) plus pnpm's `pnpm:devPreinstall` — so a manifest declaring any of
+// them, ROOT or member, needs an install even with no dependencies. dependency-free is NOT
+// install-free. The list is CLOSED and stated: a hook from a manager this tool has never heard of is
+// the honest residual of a closed-world check, the same shape as EXTERNAL_WORKSPACE_MANIFESTS.
+export const INSTALL_LIFECYCLE_SCRIPTS = Object.freeze(['preinstall', 'install', 'postinstall', 'prepare', 'preprepare', 'postprepare', 'prepublish', 'pnpm:devPreinstall']);
+// Fail-closed like the dependency check: a `scripts` field of the wrong SHAPE, or a lifecycle key
+// present with a NON-STRING value, is 'unknown' (never "no hook"). An empty-string value is a no-op,
+// not a trigger; 'has' only when a lifecycle key holds a non-empty command string.
+const installHookVerdict = (pkg) => {
+  if (!Object.hasOwn(pkg, 'scripts')) return 'none';
+  const scripts = pkg.scripts;
+  if (scripts === null || typeof scripts !== 'object' || Array.isArray(scripts)) return 'unknown';
+  let verdict = 'none';
+  for (const name of INSTALL_LIFECYCLE_SCRIPTS) {
+    if (!Object.hasOwn(scripts, name)) continue;
+    if (typeof scripts[name] !== 'string') return 'unknown';
+    if (scripts[name].length > 0) verdict = 'has';
+  }
+  return verdict;
+};
+// A native-addon manifest triggers an implicit `node-gyp rebuild` on install even with an empty
+// scripts block, so its presence — root or member — is a mandatory install, never proof of none.
+const declaresNativeBuild = (fs, dir) => lstatNoFollow(fs.lstat, join(dir, 'binding.gyp')) !== null;
+
+// 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
+// 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
+// cannot enumerate — an absent/unparseable package.json, a malformed dependency or scripts field,
+// an install-lifecycle script, a native-addon manifest (binding.gyp), an external workspace
+// manifest — leaves the posture UNKNOWN, and unknown keeps the existing install advice: a false
+// "nothing to install" is worse than a redundant hint.
+const declaresNoDependencies = ({ wtRoot, fs }) => {
+  const pkg = readPackageJson(fs, join(wtRoot, 'package.json'));
+  if (pkg === null || dependencyFieldsVerdict(pkg) !== 'none' || installHookVerdict(pkg) !== 'none') return false;
+  if (Object.hasOwn(pkg, 'workspaces')) return false;
+  if (declaresNativeBuild(fs, wtRoot)) return false;
+  // A workspace set can be declared OUTSIDE package.json too. The list is CLOSED and stated: an
+  // exotic third manifest this tool has never heard of would still read as proof, which is the
+  // honest residual of a closed-world check (the same shape as INSTALL_LIFECYCLE_SCRIPTS).
+  for (const manifest of EXTERNAL_WORKSPACE_MANIFESTS) {
+    if (lstatNoFollow(fs.lstat, join(wtRoot, manifest)) !== null) return false;
+  }
+  return true;
+};
+
 // What the RECORD states about installing — the resolved posture for THIS worktree (the runnable
 // isolated-install command, or the honest by-hand advice), never a lane-dependent hint. Probed on
-// the LIVE worktree after the node_modules step: a plain `cd … && install` through a SYMLINKED
-// node_modules writes into MAIN — never presented as isolated; the symlink case records the
-// unlink-first form instead (the same contract the --install lane already prints).
-const resolveInstallPosture = ({ root, wtRoot, fs }) => {
-  const advice = resolveInstallAdvice({ root, wtRoot, fs });
+// the LIVE worktree after the node_modules step, and LIVE STATE WINS: a symlinked node_modules
+// records the unlink-first form even on a dependency-free checkout (`--resume` can meet a symlink
+// 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 nmPath = join(wtRoot, 'node_modules');
   const nm = lstatNoFollow(fs.lstat, nmPath);
-  if (nm === null || !nm.isSymbolicLink()) return advice.instruction;
-  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 (nm !== null && nm.isSymbolicLink()) {
+    const advice = resolveInstallAdvice({ root, 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;
 };
 
-const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, report }) => {
+const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, dependencyFree, git, fs, report }) => {
   const install = resolveInstallAdvice({ root, wtRoot, fs });
   if (installFlag) {
     const dst = join(wtRoot, 'node_modules');
@@ -1280,6 +1373,22 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, re
       : `  node_modules: install it yourself (zero spawn): ${install.instruction}`);
     return 'install-printed';
   }
+  // LIVE STATE WINS the whole default lane: a node already at the worktree — a directory, or a
+  // symlink an earlier provision left, even dangling — is what the record states; reporting
+  // MAIN's state (`absent`) beside an existing node would contradict record.install.
+  const dst = join(wtRoot, 'node_modules');
+  if (lstatNoFollow(fs.lstat, dst) !== null) {
+    report.push('  node_modules: already present in the worktree');
+    return 'present';
+  }
+  // Only then may a PROVEN dependency-free checkout short-circuit the rest. Composing the posture
+  // into one of the arms below instead produced a self-contradicting line ("after your own
+  // install there, re-run --resume, or: no install needed"). `--install` is untouched above —
+  // that request was explicit.
+  if (dependencyFree) {
+    report.push(`  node_modules: ${NO_DEPENDENCIES_POSTURE}`);
+    return NODE_MODULES_NONE;
+  }
   const mainNm = join(root, 'node_modules');
   const node = classifyNodeNoFollow(mainNm, fs);
   if (node.kind === 'absent') {
@@ -1313,11 +1422,6 @@ const provisionNodeModules = ({ root, rootReal, wtRoot, installFlag, git, fs, re
     report.push(`  node_modules: main's resolves outside the repo — not symlinked; ${install.instruction}`);
     return 'outside-repo';
   }
-  const dst = join(wtRoot, 'node_modules');
-  if (lstatNoFollow(fs.lstat, dst) !== null) {
-    report.push('  node_modules: already present in the worktree');
-    return 'present';
-  }
   guardDst(fs, wtRoot, dst);
   try {
     fs.symlink(mainNm, dst);
@@ -1544,7 +1648,10 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
 
   writeSeedPlan({ wtRoot: targetPath, srcAbs: seed.srcAbs, name: seed.name, fs, report });
   const includesRecorded = provisionIncludes({ rootReal, wtRoot: targetPath, includeSources, git, fs, report, copied });
-  const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, git, fs, report });
+  // Computed ONCE, from the satellite's own checkout, and threaded to both consumers — the report
+  // lane and the record must state the SAME verdict.
+  const dependencyFree = declaresNoDependencies({ wtRoot: targetPath, fs });
+  const nodeModulesMode = provisionNodeModules({ root, rootReal, wtRoot: targetPath, installFlag: flags.install, dependencyFree, git, fs, report });
   const vscodeMode = provisionVscode({ root, wtRoot: targetPath, slug, git, fs, report });
 
   rebasePins({ root, wtRoot: targetPath, git, fs, report });
@@ -1559,7 +1666,7 @@ const finishProvision = ({ root, rootReal, targetPath, slug, branch, flags, seed
       includes: includesRecorded,
       nodeModules: nodeModulesMode,
       vscode: vscodeMode,
-      install: resolveInstallPosture({ root, wtRoot: targetPath, fs }),
+      install: resolveInstallPosture({ root, wtRoot: targetPath, dependencyFree, fs }),
       ...orientationFields({ root, slug }),
     },
     fs,