@sabaiway/agent-workflow-kit 14.14.0 → 14.14.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.
 
+## 14.14.1 — the agents writer stops on a project folder given as a symlink, before it reads or writes anything (AD-161)
+
+**`cheap-agents.mjs --cwd <dir>` now refuses a `<dir>` that is itself a symlink.** Until 14.14.1 an `--apply` there
+wrote the vehicles through the link. With a hand-edited executor it placed `changelog-skeleton.md` and then failed on
+the executor with an uncoded error, leaving `.claude/agents/` half placed; with a trailing `/` even that executor was
+rewritten through the link.
+
+- **The refusal.** `<link>`, `<link>/` and `<link>/.` stop with `CHEAP_AGENTS_SYMLINK`, exit 1, and a message naming
+  the project root as a symlink the writer refuses to write through. It is the first step of `--dry-run` and
+  `--apply` alike and of a direct `preflightCheapAgents` call: nothing under the root is read, nothing is written.
+- **What stays.** A real directory, a regular file, an absent path and a project reached through a linked parent
+  directory get the same answers as in 14.14.0, and so does the default, the current directory. The mode doc's
+  symlink-safe line and the tool header name the project root.
+
 ## 14.14.0 — the Recommendations screen lists each step of the reference setup you have not taken or declined, with its preview command or the reason it has none (AD-160)
 
 **`/agent-workflow-kit recommendations` now shows what your project still lacks of the full flow.** Until 14.14.0

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". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
 disable-model-invocation: true
 metadata:
-  version: '14.14.0'
+  version: '14.14.1'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

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

@@ -19,7 +19,7 @@ Writing code, running gates, and user-facing copy never move to these four vehic
 Run `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs [--dry-run | --apply] [--cwd <dir>]`:
 
 1. **`--dry-run` first, always** (the default — changes nothing). It previews, per bundled vehicle, whether it **would place** the file, finds it **already current**, or finds a **customized** file (different content) that will be **preserved, never overwritten** (delete the file to reseed it from the bundle) — except the executor, whose differing bytes **would re-derive** from `docs/ai/vehicles.json` and are rewritten on `--apply` (a hand edit is replaced, never preserved).
-2. **Only on an explicit yes**, re-run with `--apply`. It writes **only** under `.claude/agents/` — never `settings.json` / `settings.local.json`, never a commit. `--apply` is deployment-gated (the stamp must be at the lineage head) and symlink-safe (a symlinked `.claude` / `.claude/agents` / target file is a STOP).
+2. **Only on an explicit yes**, re-run with `--apply`. It writes **only** under `.claude/agents/` — never `settings.json` / `settings.local.json`, never a commit. `--apply` is deployment-gated (the stamp must be at the lineage head) and symlink-safe (a symlinked project root / `.claude` / `.claude/agents` / target file is a STOP, in a `--dry-run` too).
 3. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) so the placed files stay invisible to `git status` — `/.claude/agents/` is in the known-footprint registry; the apply report reminds you.
 
 **Invariants:** writer (writes only `.claude/agents/`) · preview by default · a diverged existing file is reported and preserved, never clobbered — except the executor, re-derived from `docs/ai/vehicles.json` on apply · never touches settings · never commits · **no READ-ONLY vehicle grants `Bash`, and exactly one bundled vehicle, `executor`, grants a shell** · the cheap-lane vehicles are pinned to `model: haiku` + `effort: low`, and the review lens is pinned OFF the cheap model (all content-tested).

package/tools/cheap-agents.mjs

@@ -12,8 +12,8 @@
 //   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
 //     head (a dry-run stays usable whatever the stamp says; an unreadable orchestration config
 //     STOPs both, since the derived lenses it names cannot be known);
-//   • symlink-safe — a symlinked `.claude` / `.claude/agents` / target file is a STOP, never a
-//     write-through;
+//   • symlink-safe — a symlinked project root, `.claude`, `.claude/agents` or target file is a
+//     STOP, in a dry-run too, never a write-through;
 //   • preserves differing .claude/agents/ files (`customized — preserved`), except the executor:
 //     on apply its body is re-derived from docs/ai/vehicles.json, replacing a hand edit;
 //     an identical file is `already current` (idempotent re-run);
@@ -31,7 +31,7 @@
 // Dependency-free, Node >= 22. No side effects on import.
 
 import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
@@ -117,9 +117,21 @@ const writeFsDeps = (deps = {}) => ({
   writeFile: deps.writeFile ?? writeFileSync,
 });
 
+const refuseSymlinkedRoot = (projectDir, deps) => {
+  const root = resolve(projectDir);
+  let stat;
+  try {
+    stat = readFsDeps(deps).lstat(root);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) throw makeCheapAgentsError(CHEAP_AGENTS_SYMLINK, `the project root ${root} is a symlink — refusing to write through it`);
+};
+
 export const preflightCheapAgents = ({ cwd, derived = [] }, deps = {}) => {
   const fs = readFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
+  refuseSymlinkedRoot(projectDir, deps);
   const templatesByName = new Map(readBundledAgents(deps).map((template) => [template.name, template]));
   for (const template of derived) templatesByName.set(template.name, template);
   const templates = [...templatesByName.values()];
@@ -169,6 +181,7 @@ export const applyCheapAgentsCommand = (root) =>
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const fs = writeFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
+  refuseSymlinkedRoot(projectDir, deps);
   const posture = loadExecutorPostureOrStop(projectDir, deps);
   const derived = [executorTemplate(posture, deps), ...configuredDerivedTemplates(projectDir, deps)];
   const preflight = preflightCheapAgents({ cwd: projectDir, derived }, deps);