agentopology 0.5.2 → 0.6.0

package/dist/scaffold/merge.js

@@ -107,24 +107,38 @@ export function deepMergeJson(existingRaw, generatedRaw) {
         return existingRaw;
     }
     const merged = mergeObjects(existing, generated);
+    // Nothing to add: keep the user's bytes, formatting included.
+    if (JSON.stringify(merged) === JSON.stringify(existing))
+        return existingRaw;
     return JSON.stringify(merged, null, 2) + "\n";
 }
 /**
  * Merge settings.json files with domain-aware logic for Claude Code settings.
  *
+ * The user's file is the base; scaffold only adds or replaces what it owns.
+ *
  * Rules:
- *   - permissions.allow: union-merge (deduplicated)
- *   - permissions.deny: union-merge (deduplicated)
+ *   - permissions: every existing key is kept (ask, defaultMode,
+ *     additionalDirectories, ...); allow, deny and ask arrays are
+ *     union-merged; a generated scalar is added only where none exists
  *   - env: shallow-merge (generated wins on key conflict)
- *   - hooks: rewritten entirely from generated (topology owns hooks)
+ *   - hooks: a hook group is the topology's when one of its commands names a
+ *     path in `ownedPaths`; those are replaced by the generated hooks, and
+ *     every other group — the user's — is kept. Without `ownedPaths`, nothing
+ *     existing is treated as owned, so nothing is removed
  *   - All other top-level keys: existing wins (user-only keys preserved)
  *
+ * This used to rebuild permissions from allow/deny alone and replace hooks
+ * wholesale, so a re-scaffold deleted the user's own hooks, ask rules and
+ * defaultMode, and two topologies in one repo deleted each other's hooks.
+ *
  * @param existingRaw - Current settings.json content on disk (JSON string, or empty string)
  * @param generatedRaw - Freshly generated settings.json content (JSON string)
+ * @param ownedPaths - Paths this topology writes or wrote (generated + manifest)
  * @returns Merged JSON string
  * @throws {Error} if existingRaw is non-empty and is invalid JSON
  */
-export function deepMergeSettingsJson(existingRaw, generatedRaw) {
+export function deepMergeSettingsJson(existingRaw, generatedRaw, ownedPaths = []) {
     // Empty existing means first scaffold — return generated unchanged
     if (existingRaw.trim() === "") {
         return generatedRaw;
@@ -145,22 +159,35 @@ export function deepMergeSettingsJson(existingRaw, generatedRaw) {
     }
     // Start with existing (preserves all user-only top-level keys)
     const merged = { ...existing };
-    // --- permissions: union-merge allow and deny arrays ---
-    const existingPerms = (existing.permissions ?? {});
-    const generatedPerms = (generated.permissions ?? {});
-    if (generated.permissions !== undefined || existing.permissions !== undefined) {
-        const mergedPerms = {};
-        for (const key of ["allow", "deny"]) {
-            const ex = Array.isArray(existingPerms[key]) ? existingPerms[key] : [];
-            const gen = Array.isArray(generatedPerms[key]) ? generatedPerms[key] : [];
-            const union = Array.from(new Set([...ex, ...gen]));
-            if (union.length > 0) {
+    // --- permissions: keep every existing key; union the rule arrays ---
+    if (isPlainObject(generated.permissions) || isPlainObject(existing.permissions)) {
+        const ex = isPlainObject(existing.permissions) ? existing.permissions : {};
+        const gen = isPlainObject(generated.permissions) ? generated.permissions : {};
+        const mergedPerms = { ...ex };
+        for (const [key, value] of Object.entries(gen)) {
+            const current = mergedPerms[key];
+            if (Array.isArray(value) || Array.isArray(current)) {
+                const union = Array.from(new Set([
+                    ...(Array.isArray(current) ? current : []),
+                    ...(Array.isArray(value) ? value : []),
+                ]));
                 mergedPerms[key] = union;
             }
+            else if (current === undefined) {
+                mergedPerms[key] = value;
+            }
+        }
+        for (const key of Object.keys(mergedPerms)) {
+            if (Array.isArray(mergedPerms[key]) && mergedPerms[key].length === 0) {
+                delete mergedPerms[key];
+            }
         }
         if (Object.keys(mergedPerms).length > 0) {
             merged.permissions = mergedPerms;
         }
+        else {
+            delete merged.permissions;
+        }
     }
     // --- env: shallow-merge, generated wins on conflict ---
     if (generated.env !== undefined) {
@@ -168,12 +195,12 @@ export function deepMergeSettingsJson(existingRaw, generatedRaw) {
         const generatedEnv = generated.env;
         merged.env = { ...existingEnv, ...generatedEnv };
     }
-    // --- hooks: rewritten entirely from generated (topology owns hooks) ---
-    if (generated.hooks !== undefined) {
-        merged.hooks = generated.hooks;
+    // --- hooks: replace the topology's own groups, keep the user's ---
+    const mergedHooks = mergeHooks(existing.hooks, generated.hooks, ownedPaths);
+    if (mergedHooks) {
+        merged.hooks = mergedHooks;
     }
     else {
-        // No hooks in generated — remove the hooks key (topology no longer declares any)
         delete merged.hooks;
     }
     // --- all other generated keys: add if missing, do NOT overwrite existing ---
@@ -184,8 +211,72 @@ export function deepMergeSettingsJson(existingRaw, generatedRaw) {
             merged[key] = value;
         }
     }
+    // Nothing to add: keep the user's bytes, formatting included.
+    if (JSON.stringify(merged) === JSON.stringify(existing))
+        return existingRaw;
     return JSON.stringify(merged, null, 2) + "\n";
 }
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/**
+ * Identity of a hook group for deduplication: matcher plus each command with
+ * the project-dir prefix, quotes and "./" removed. An imported hook written
+ * as `bash .claude/hooks/x.sh` and the same hook compiled as
+ * `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/x.sh"` are one hook, not two that
+ * both fire.
+ */
+function hookGroupKey(group) {
+    if (!isPlainObject(group) || !Array.isArray(group.hooks))
+        return JSON.stringify(group);
+    const commands = group.hooks.map((h) => isPlainObject(h) && typeof h.command === "string"
+        ? h.command.replace(/"?\$CLAUDE_PROJECT_DIR\/?/g, "").replace(/["']/g, "").replace(/(^|\s)\.\//g, "$1").replace(/\s+/g, " ").trim()
+        : JSON.stringify(h));
+    return JSON.stringify([group.matcher ?? "", commands]);
+}
+/** Whether a hook group runs a script this topology owns. */
+function isOwnedHookGroup(group, scripts) {
+    if (!isPlainObject(group) || !Array.isArray(group.hooks))
+        return false;
+    return group.hooks.some((h) => {
+        if (!isPlainObject(h) || typeof h.command !== "string")
+            return false;
+        const tokens = h.command.split(/\s+/).map((t) => t.replace(/^\.\//, ""));
+        return tokens.some((t) => scripts.includes(t));
+    });
+}
+/**
+ * Per event: the user's groups first, then the generated ones, deduplicated.
+ * Returns undefined when no event keeps any group.
+ */
+function mergeHooks(existingHooks, generatedHooks, ownedPaths) {
+    // Config files are never hook scripts; matching them would claim a user hook
+    // that merely mentions CLAUDE.md.
+    const scripts = ownedPaths
+        .filter((p) => !/\.(md|json)$/.test(p))
+        .map((p) => p.replace(/^\.\//, ""));
+    const ex = isPlainObject(existingHooks) ? existingHooks : {};
+    const gen = isPlainObject(generatedHooks) ? generatedHooks : {};
+    const out = {};
+    for (const event of new Set([...Object.keys(ex), ...Object.keys(gen)])) {
+        // A group generated again stays where it is, so reruns (and two
+        // topologies taking turns) do not reorder the file.
+        const regenerated = new Set((Array.isArray(gen[event]) ? gen[event] : []).map(hookGroupKey));
+        const kept = (Array.isArray(ex[event]) ? ex[event] : []).filter((g) => regenerated.has(hookGroupKey(g)) || !isOwnedHookGroup(g, scripts));
+        const seen = new Set();
+        const groups = [];
+        for (const g of [...kept, ...(Array.isArray(gen[event]) ? gen[event] : [])]) {
+            const key = hookGroupKey(g);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            groups.push(g);
+        }
+        if (groups.length > 0)
+            out[event] = groups;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
 function mergeObjects(existing, generated) {
     // Start with a copy of existing (preserves user-only keys)
     const result = { ...existing };

package/dist/scaffold/merge.js.map

@@ -1 +1 @@
-{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/scaffold/merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;GAGG;AACH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,2BAA2B,CAAC;QACrC,KAAK,aAAa,CAAC;QACnB;YACE,OAAO,+BAA+B,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,SAAiB,EACjB,OAAe;IAEf,MAAM,kBAAkB,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE1D,gDAAgD;IAChD,MAAM,YAAY,GAAG,+BAA+B,CAClD,QAAQ,EACR,iBAAiB,EACjB,kBAAkB,CACnB,CAAC;IAEF,wEAAwE;IACxE,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,yDAAyD;IACzD,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;IACpD,MAAM,UAAU,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,+DAA+D;QAC/D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,sFAAsF;IACtF,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAE3C,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACzB,KAAK,MAAM,EAAE,IAAI,kBAAkB,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,IAAI,MAAM,CAC1B,IAAI,EAAE,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,OAAO,EACpD,GAAG,CACJ,CAAC;QACF,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,OAAO,IAAI,OAAO,CAAC,KAAK,GAAG,MAAM,EAAE,CAAC;YACtC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QACzB,CAAC;IACH,CAAC;IAED,+FAA+F;IAC/F,MAAM,aAAa,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAExC,OAAO,aAAa,GAAG,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,YAAY,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,eAAuB,EACvB,YAAoB;IAEpB,OAAO,WAAW,CAAC,eAAe,CAAC,KAAK,YAAY,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB,EAAE,YAAoB;IACrE,IAAI,QAAiC,CAAC;IACtC,IAAI,SAAkC,CAAC;IAEvC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACnC,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;QAC7D,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB,EAAE,YAAoB;IAC7E,mEAAmE;IACnE,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,QAAiC,CAAC;IACtC,IAAI,SAAkC,CAAC;IAEvC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,2CAA4C,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,CAAC;QACH,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,4CAA6C,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,+DAA+D;IAC/D,MAAM,MAAM,GAA4B,EAAE,GAAG,QAAQ,EAAE,CAAC;IAExD,yDAAyD;IACzD,MAAM,aAAa,GAAG,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,CAA6B,CAAC;IAC/E,MAAM,cAAc,GAAG,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,CAA6B,CAAC;IAEjF,IAAI,SAAS,CAAC,WAAW,KAAK,SAAS,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9E,MAAM,WAAW,GAA6B,EAAE,CAAC;QACjD,KAAK,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAU,EAAE,CAAC;YAC7C,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACvE,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACnD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;QACnC,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,IAAI,SAAS,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,EAAE,CAA2B,CAAC;QACnE,MAAM,YAAY,GAAG,SAAS,CAAC,GAA6B,CAAC;QAC7D,MAAM,CAAC,GAAG,GAAG,EAAE,GAAG,WAAW,EAAE,GAAG,YAAY,EAAE,CAAC;IACnD,CAAC;IAED,yEAAyE;IACzE,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;IACjC,CAAC;SAAM,CAAC;QACN,iFAAiF;QACjF,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,8EAA8E;IAC9E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,OAAO;YAAE,SAAS;QACxE,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,YAAY,CACnB,QAAiC,EACjC,SAAkC;IAElC,2DAA2D;IAC3D,MAAM,MAAM,GAA4B,EAAE,GAAG,QAAQ,EAAE,CAAC;IAExD,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE9B,IACE,QAAQ,KAAK,IAAI;YACjB,OAAO,QAAQ,KAAK,QAAQ;YAC5B,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YACxB,OAAO,KAAK,IAAI;YAChB,OAAO,OAAO,KAAK,QAAQ;YAC3B,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EACvB,CAAC;YACD,6BAA6B;YAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CACxB,OAAkC,EAClC,QAAmC,CACpC,CAAC;QACJ,CAAC;aAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACjC,iCAAiC;YACjC,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC;QACzB,CAAC;QACD,mFAAmF;IACrF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../src/scaffold/merge.ts"],"names":[],"mappings":"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"}

package/dist/scaffold/types.d.ts

@@ -49,5 +49,22 @@ export type FileAction = {
     path: string;
     content: string;
     detail: string;
+}
+/**
+ * Never written or deleted, even with --force. `unsafe` marks a path that
+ * must abort the whole run before anything is written (an empty or
+ * malformed file name — the EISDIR class).
+ */
+ | {
+    type: "blocked";
+    path: string;
+    detail: string;
+    unsafe?: boolean;
+}
+/** A create-only file already there: the user's. Never written or claimed. */
+ | {
+    type: "kept";
+    path: string;
+    detail: string;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/scaffold/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scaffold/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;CAC5D;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACtC;AAED,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACvF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scaffold/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,QAAQ,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,CAAC;CAC5D;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACtC;AAED,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACvF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACrE;;;;GAIG;GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE;AACrE,8EAA8E;GAC5E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentopology",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "The declarative language for multi-agent systems. Write once, scaffold for any platform.",
   "author": "Nadav Naveh",
   "license": "Apache-2.0",

package/spec/grammar.md

@@ -368,6 +368,7 @@ scale-field     = 'mode' ':' ('auto' | 'fixed' | 'config')
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
+| `file` | string | no | -- | Project-relative path of the hand-written file holding this node's internals. Bindings reference it and never generate or overwrite it (V97). `import` sets it on every file it did not generate, so a hand-built system comes in without losing anything. |
 | `role` | identifier | no | -- | Maps to a role defined in the `roles` block |
 | `model` | model-id | yes | -- | LLM model identifier (e.g., `opus`, `gpt-4o`, `gemini-pro`) |
 | `permissions` | perm-enum | no | `autonomous` | Permission mode |
@@ -1088,7 +1089,7 @@ Environment blocks have no fixed schema -- fields are identifier/string key-valu
 ```ebnf
 triggers        = 'triggers' '{' command-decl* '}'
 command-decl    = 'command' identifier '{' command-fields '}'
-command-fields  = 'pattern' ':' string ('argument' ':' template-var)?
+command-fields  = 'pattern' ':' string ('argument' ':' template-var)? ('file' ':' string)?
 ```
 
 ```agenttopology
@@ -1108,6 +1109,7 @@ triggers {
 |-------|------|----------|---------|
 | `pattern` | string | yes | -- |
 | `argument` | template-var | no | -- |
+| `file` | string | no | -- |
 
 ---
 
@@ -1117,9 +1119,12 @@ triggers {
 hooks           = 'hooks' '{' hook-decl* '}'
 hook-decl       = 'hook' identifier '{' hook-fields '}'
 hook-fields     = ('on' ':' hook-event | 'matcher' ':' string | 'run' ':' string
-                  | 'type' ':' hook-type | 'timeout' ':' number)*
-hook-event      = <universal-event> | <platform-event>
-hook-type       = 'command' | 'prompt'
+                  | 'type' ':' hook-type | 'flag' ':' env-name | 'timeout' ':' number)*
+hook-event      = <universal-event> | <platform-event> | <engine-event>
+hook-type       = 'command' | 'prompt' | 'mod'
+engine-event    = 'tool.call' | 'prompt.submit' | 'prompt.context' | 'session.start'
+                | 'session.end' | 'model.complete' | 'message.received'
+
 ```
 
 **Universal hook events** -- these are defined by the spec and must be supported by all bindings:
@@ -1170,8 +1175,14 @@ hooks {
 | `matcher` | string | no | -- |
 | `run` | string | yes | -- |
 | `type` | hook-type | no | `command` |
+| `flag` | env-name | no (mod only) | -- |
 | `timeout` | number | no | `600` |
 
+A `type: mod` hook is a TypeScript module loaded inside the engine (Claude
+Code function hooks). Its `on:` is an `engine-event` (V95); a command or
+prompt hook takes a PascalCase event. `flag:` names the env variable that
+switches the Mod on. Fields are one per line (V90).
+
 ---
 
 ### 4.17 `settings`
@@ -1351,6 +1362,10 @@ agent processor {
 
 ---
 
+### 4.20a `file:` — hand-written internals
+
+Any node (`agent`, `group`, `human`, ...), any `skill` and any trigger `command` may carry `file: "<project-relative path>"`. It says: the structure is described here, the internals live in that file, and they are the author's. A binding never generates or overwrites a file so marked; for a skill it leaves the whole skill folder alone, for a group its skill and runtime folder too. Gates and hooks still wire to the node by name. `agentopology import` sets `file:` on every file it finds that no scaffold manifest lists as generated, which is what makes import followed by scaffold lossless.
+
 ### 4.21 `skill` (declarations)
 
 Topology-level skill declarations. Each `skill` block declares a self-contained application that bundles executable scripts, domain knowledge, reference docs, and instructions into a coherent capability. Agents load skills via their `skills` field.
@@ -1394,6 +1409,7 @@ skill classification {
 
 | Field | Type | Required | Default |
 |-------|------|----------|---------|
+| `file` | string | no | -- |
 | `description` | string | no | -- |
 | `scripts` | name-list | no | `[]` |
 | `domains` | path-list | no | `[]` |

package/spec/testing.md

@@ -0,0 +1,81 @@
+# Testing spec: what the suite proves
+
+Every guarantee has an id. A test carries that id in its name (`[G3] ...`), and
+`src/__tests__/spec-testing-sync.test.ts` fails when an id here has no test, or
+a test names an id that isn't here. Open findings are listed as `it.todo` in
+`src/__tests__/open-findings.test.ts`, so the suite shows what is not yet
+guaranteed instead of hiding it.
+
+## How to run
+
+| Suite | Command | Needs |
+|---|---|---|
+| Everything offline (unit, CLI, e2e) | `npx vitest run` | nothing; the build runs first (vitest globalSetup), so tests never see a stale `dist/` |
+| Live Claude Code | `AT_LIVE=1 npx vitest run src/__tests__/live` | the `claude` CLI; one small haiku call per project; `AT_CLAUDE_BIN` overrides the binary |
+
+Run the live suite before every release, and after any change to a binding.
+
+## Guarantees
+
+| Id | Guarantee | Where |
+|---|---|---|
+| G1 | The first scaffold keeps a file it did not create (conflict, kept unless `--force`) | e2e/scaffold-owns.test.ts |
+| G2 | Scaffold never writes or deletes through a symlink, even with `--force` | e2e/scaffold-owns.test.ts |
+| G3 | Re-scaffolding keeps the user's hooks, `ask`, `defaultMode` and other permission keys | e2e/scaffold-owns.test.ts |
+| G4 | A second scaffold with no changes writes nothing | e2e/scaffold-owns.test.ts |
+| G5 | `--dry-run` writes nothing | e2e/scaffold-owns.test.ts |
+| G6 | Prose in a gate's `run` fails validate (V96) and scaffold, and nothing is written | e2e/scaffold-owns.test.ts |
+| G7 | An edited file that scaffold owns is kept on the next run | e2e/scaffold-owns.test.ts |
+| G8 | `--prune` removes untouched leftovers and keeps edited ones | e2e/scaffold-owns.test.ts |
+| G9 | Two topologies in one project keep separate manifests | e2e/scaffold-owns.test.ts |
+| G10 | No `${…}` reference or `#`-key reaches settings `env` (Claude Code applies env literally) | e2e/scaffold-owns.test.ts |
+| G11 | An unsafe generated path aborts the run before any file is written | scaffold/__tests__/safety.test.ts |
+| G12 | A second scaffold of an imported project changes nothing | e2e/roundtrip.test.ts |
+| G13 | An agent's `extensions` never leak into project-wide settings (only a topology-level `extensions` block is top-level) | e2e/roundtrip.test.ts |
+| G14 | An imported hook and its compiled form (`$CLAUDE_PROJECT_DIR`) merge as one hook, not two | e2e/roundtrip.test.ts |
+| G15 | V97 refuses a `file:` outside the project | e2e/roundtrip.test.ts |
+| G16 | Scaffold names every hand-written `file:` the project lacks | e2e/roundtrip.test.ts |
+| G17 | V11 does not demand a flow path for an on-demand (`invocation: manual`) agent | e2e/roundtrip.test.ts |
+| R1 | Import then scaffold keeps every hand-built file (was: 37 of 72 missing) | e2e/roundtrip.test.ts |
+| R2 | Import then scaffold leaves every hand-built file byte-identical, settings.json included (was: 2,957 lines cut to 1,706) | e2e/roundtrip.test.ts |
+| R3 | The imported .at validates with no errors (was: 22) | e2e/roundtrip.test.ts |
+| R4 | Import keeps frontmatter the language has no field for, comma-string lists, and the real `permissions` block | e2e/roundtrip.test.ts |
+| A4 | Agents, groups, skills and commands found on disk are imported with `file:` and never generated | e2e/roundtrip.test.ts |
+| F3 | `--allow-invalid` compiles despite validation errors; `--force` only overwrites kept files | e2e/roundtrip.test.ts |
+| C5 | A hook's own script is created only when missing: never overwritten (even with `--force`), reported or claimed | e2e/roundtrip.test.ts |
+| L2 | Real Claude Code loads a hand-built project after import then scaffold | live/claude-code.live.test.ts |
+| L1 | Real Claude Code loads every scaffolded example: every agent, skill and command registers, and the session succeeds | live/claude-code.live.test.ts |
+
+## Open findings (not yet guaranteed)
+
+Each is an `it.todo` with the same id. When one is fixed, its todo becomes a
+real test and the row moves to Guarantees. Source: the compile audit,
+2026-10-28/29 (plan page and `.history/2026-10-28-content-harness-gaps.md`).
+
+| Id | Finding | Phase |
+|---|---|---|
+| N11 | sync pulls generated prose back into the .at, so the prompt grows each cycle | 2 |
+| N12 | A skill `prompt: "path"` emits `See: path`; the instructions never reach Claude | 2 |
+| A3 | `kind: external` actions ignore `commands:` and emit a TODO stub | 3 |
+| A3b | Tools with a real `script:` get stub copies | 3 |
+| B4 | Schedule scripts call the wrong action path; `every:` becomes a commented-out cron line | 3 |
+| H1 | Human nodes compile to frontmatter-less AGENT.md files that Claude Code ignores; they should be an approval step | 3 |
+| N4 | `.mcp.json` drops `type`, so a url server is skipped | 3 |
+| N5 | `type: prompt` hooks are emitted as commands | 3 |
+| N6 | Universal events (AgentStop, ToolUse, Error) are emitted unmapped, so the hook never fires | 3 |
+| N7 | MCP tool names: whole-server and dotted names mis-converted; permissions not converted | 3 |
+| N8 | V27 accepts `confirm` and `bypass`, emitted as invalid `permissionMode` | 3 |
+| N9 | A hook matcher with a regex breaks the agent file's YAML | 3 |
+| N10 | `invocation: manual` drops the description, so the agent is not registered | 3 |
+| N14 | `settings.ask` is parsed but never emitted | 3 |
+| N16 | Model ids are not checked per target | 3 |
+| N17 | Unquoted YAML scalars change type (`yes` becomes `true`) | 3 |
+| N18 | No reference checks for `skills:`, `mcp-servers:`, skill `agent:` | 3 |
+| N19 | Hook stubs carry the date, so output is not byte-stable | 3 |
+| C1 | `scaffold --dry-run` says settings.json and .mcp.json would be "config merged" but does not show the diff (content session, 2026-10-29) | 3 |
+| C2 | Scaffold adds `.claude/CLAUDE.md`, which competes with a project's root CLAUDE.md (content session, 2026-10-29) | 3 |
+| C3 | Run-line parsing takes placeholders and file arguments as scripts (`SLUG`, `frames-critic.json`) and plans stubs for them (content session, 2026-10-29) | 3 |
+| C4 | A gate whose `after:` is an action or a human compiles to no enforceable hook (10 gates in content-harness) | 3 |
+| B5 | An agent's permissions read as per-agent grants; Claude Code allow rules are session-wide | 4 |
+| F1 | Missing first-class fields: agent effort, initialPrompt, omitClaudeMd, cache TTL, color; skill when_to_use, arguments, paths, shell | 4 |
+| F2 | Hooks as a typed union (http, mcp_tool, agent; once, async, if) | 4 |

package/spec/validation.md

@@ -665,7 +665,7 @@ agent researcher {
 
 ## Summary Table
 
-All 93 rules, generated from `src/parser/validator.ts` so the spec cannot drift
+All 97 rules, generated from `src/parser/validator.ts` so the spec cannot drift
 from the implementation. Rules V8, V12, V23, V24, V89 and V90 are collected at
 **parse time** — the misuse they catch leaves no trace in the AST — and surfaced
 through the validator like any other rule.
@@ -684,7 +684,7 @@ through the validator like any other rule.
 | V8 | error/warning | Import references should resolve (warning only -- we cannot check the filesystem) |
 | V9 | error/warning | Every action referenced in flow must appear in orchestrator.handles |
 | V10 | error/warning | Prompt content should not be empty if a prompt block is declared |
-| V11 | error | If agent A writes X and agent B reads X, a path A -> B must exist in flow |
+| V11 | error | If agent A writes X and agent B reads X, a path A -> B must exist in flow — unless either is on demand (`invocation: manual`), which has no flow by definition |
 | V12 | error | Edge attribute order must be [when, max, per] |
 | V13 | error | Gate `after` and `before` must reference declared nodes |
 | V14 | error | `tools` and `disallowed-tools` cannot both appear on the same agent |
@@ -767,6 +767,10 @@ through the validator like any other rule.
 | V91 | error | A required field must not be satisfied by a parser-injected placeholder — `meta.version` and `orchestrator.model` are required, and their sentinels (`0.0.0`, `unknown`) satisfied every downstream check |
 | V92 | error | An edge's attributes go in ONE bracket, comma-separated — `[when ...] [max N]` produced a condition string containing brackets, silently |
 | V93 | warning | An edge between two agents that both declare paths should declare a handoff — `writer.writes \| reader.reads` empty means the receiver runs after the sender with none of its output |
+| V94 | error | A hook's `type` is `command`, `prompt` or `mod`; `flag:` belongs only to a mod and is an env variable name — `type: mod` passed silently and was scaffolded as a bash command |
+| V95 | error | A hook's `on:` must fit its type — a mod takes a known engine event (`tool.call`, `prompt.submit`; five more seen in the engine warn as unproven), a command/prompt hook a PascalCase event |
+| V96 | error | A gate or hook `run` must be a command, not prose — a sentence there compiled to junk script files (`E;`, `fail:`) and crashed scaffold with EISDIR; the explanation belongs in `description` |
+| V97 | error | A node, skill or command `file:` must be a project-relative path (no `..`, not absolute, safe names) — it marks hand-written internals scaffold never writes, so it must be a path scaffold can honour |
 
 > Sections above document the first 35 rules with worked examples. The rest are
 > single-line entries here plus their doc comment in the source. Adding an