@wairon/cli 5.1.1-dev.59 → 5.1.1-dev.60

package/dist/index.js

@@ -2497,7 +2497,7 @@ var require_dist = __commonJS({
       scaffoldPack: () => scaffoldPack2
     });
     module2.exports = __toCommonJS2(src_exports2);
-    var path28 = __toESM2(require("path"));
+    var path29 = __toESM2(require("path"));
     var import_js_yaml3 = require("js-yaml");
     var import_js_yaml = require("js-yaml");
     var import_crypto = require("crypto");
@@ -3060,8 +3060,8 @@ var require_dist = __commonJS({
     function slug(name) {
       return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
     }
-    var fs18 = __toESM2(require("fs"));
-    var path29 = __toESM2(require("path"));
+    var fs19 = __toESM2(require("fs"));
+    var path30 = __toESM2(require("path"));
     var import_fflate = require_node();
     var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".hg", ".svn"]);
     function listEntries(archive) {
@@ -3099,9 +3099,9 @@ var require_dist = __commonJS({
     }
     function writeTree(destDir, files) {
       for (const file of files) {
-        const absolute = path29.join(destDir, file.path);
-        fs18.mkdirSync(path29.dirname(absolute), { recursive: true });
-        fs18.writeFileSync(absolute, file.contents);
+        const absolute = path30.join(destDir, file.path);
+        fs19.mkdirSync(path30.dirname(absolute), { recursive: true });
+        fs19.writeFileSync(absolute, file.contents);
       }
     }
     function classifyKind(name, symlinks) {
@@ -3110,14 +3110,14 @@ var require_dist = __commonJS({
       return "file";
     }
     function walkPackDir(root, current2, out) {
-      for (const entry of fs18.readdirSync(current2, { withFileTypes: true })) {
+      for (const entry of fs19.readdirSync(current2, { withFileTypes: true })) {
         if (entry.isDirectory()) {
           if (SKIP_DIRS.has(entry.name)) continue;
-          walkPackDir(root, path29.join(current2, entry.name), out);
+          walkPackDir(root, path30.join(current2, entry.name), out);
         } else if (entry.isFile()) {
-          const absolute = path29.join(current2, entry.name);
-          const relative22 = path29.relative(root, absolute).split(path29.sep).join("/");
-          out.push({ path: relative22, contents: fs18.readFileSync(absolute) });
+          const absolute = path30.join(current2, entry.name);
+          const relative22 = path30.relative(root, absolute).split(path30.sep).join("/");
+          out.push({ path: relative22, contents: fs19.readFileSync(absolute) });
         }
       }
     }
@@ -3167,7 +3167,7 @@ var require_dist = __commonJS({
     function scaffoldPack(request) {
       const files = render(request);
       writeTree(request.targetDir, files);
-      return files.map((file) => path28.join(request.targetDir, file.path));
+      return files.map((file) => path29.join(request.targetDir, file.path));
     }
     function buildPack(sourceDir) {
       const files = readPackDir(sourceDir);
@@ -3224,7 +3224,7 @@ var require_dist = __commonJS({
       }
       const manifest = parseManifest(decode(envelope.contents));
       verifyIntegrity2(manifest, files);
-      const directory = path28.resolve(destDir);
+      const directory = path29.resolve(destDir);
       writeTree(directory, files);
       const result = {
         directory,
@@ -3302,7 +3302,7 @@ var require_dist = __commonJS({
       }
       const manifest = parseTreeManifest(decode(envelope.contents));
       verifyTreeIntegrity(manifest, files);
-      const directory = path28.resolve(destDir);
+      const directory = path29.resolve(destDir);
       writeTree(directory, files);
       const result = {
         destDir: directory,
@@ -3317,7 +3317,7 @@ var require_dist = __commonJS({
       return normalized === "." ? ".wai/" : `${normalized}/.wai/`;
     }
     function normalizeRootPath(relativePath) {
-      const posix2 = relativePath.split(path28.sep).join("/").replace(/^\.\//, "").replace(/\/+$/, "");
+      const posix2 = relativePath.split(path29.sep).join("/").replace(/^\.\//, "").replace(/\/+$/, "");
       return posix2 === "" || posix2 === "." ? "." : posix2;
     }
     function slugify(projectName) {
@@ -3628,6 +3628,7 @@ __export(src_exports, {
   getSubprojectPrefix: () => getSubprojectPrefix,
   getSubsystemPath: () => getSubsystemPath,
   getTypePath: () => getTypePath,
+  globalGuideFilePath: () => globalGuideFilePath,
   globalPacksDir: () => globalPacksDir,
   globalPacksEnabled: () => globalPacksEnabled,
   globalTemplatesDir: () => globalTemplatesDir,
@@ -3644,6 +3645,7 @@ __export(src_exports, {
   importSpecTree: () => importSpecTree,
   importSurface: () => importSurface,
   ineffectiveDeltaPaths: () => ineffectiveDeltaPaths,
+  injectGuide: () => injectGuide,
   inspectChainedRoots: () => inspectChainedRoots,
   inspectTreeArchive: () => inspectTreeArchive2,
   installPackFromDirectory: () => installPackFromDirectory,
@@ -3697,6 +3699,7 @@ __export(src_exports, {
   loadTypeSpec: () => loadTypeSpec,
   loadTypeSpecs: () => loadTypeSpecs,
   localApprover: () => localApprover,
+  localGuideFilePath: () => localGuideFilePath,
   localTypesOf: () => localTypesOf,
   logger: () => logger,
   makeScopeFilter: () => makeScopeFilter,
@@ -3739,12 +3742,14 @@ __export(src_exports, {
   readProjectContext: () => readProjectContext,
   readResource: () => readResource,
   readSkillResource: () => readSkillResource,
+  readStampVersion: () => readStampVersion,
   readYamlFile: () => readYamlFile,
   rebaseProjectVariants: () => rebaseProjectVariants,
   rebaseReference: () => rebaseReference,
   recordProfileSelection: () => recordProfileSelection,
   registerExporter: () => registerExporter,
   registerPackRef: () => registerPackRef,
+  reinjectLocalGuides: () => reinjectLocalGuides,
   removeDomain: () => removeDomain,
   removePackSelection: () => removePackSelection,
   removeSnapshot: () => removeSnapshot,
@@ -3822,6 +3827,7 @@ __export(src_exports, {
   writeJsonFile: () => writeJsonFile,
   writeLockRecord: () => writeLockRecord,
   writeProjectContext: () => writeProjectContext,
+  writeRootGuideDelegator: () => writeRootGuideDelegator,
   writeYamlFile: () => writeYamlFile
 });
 module.exports = __toCommonJS(src_exports);
@@ -6400,10 +6406,10 @@ function stepGraph(method) {
     const s = byNum.get(n);
     if (s.type !== "parallel" || s.endStep === void 0 || !s.branches?.length) continue;
     const entries = s.branches.map((b) => b.step).sort((a, b) => a - b);
-    const join17 = fallNext(s.endStep);
+    const join18 = fallNext(s.endStep);
     for (let i = 0; i < entries.length; i++) {
       const armEnd = i + 1 < entries.length ? prevOf(entries[i + 1]) : s.endStep;
-      if (armEnd !== void 0 && armEnd >= entries[i]) armEndJoin.set(armEnd, join17);
+      if (armEnd !== void 0 && armEnd >= entries[i]) armEndJoin.set(armEnd, join18);
     }
   }
   const successorsOf = (n) => {
@@ -11656,7 +11662,7 @@ function defaultTargetConfig(type) {
     enabled: true
   };
 }
-var WAIRON_VERSION = "5.1.1-dev.59";
+var WAIRON_VERSION = "5.1.1-dev.60";
 var GITHUB_REPO = "SYW-Apps/Waffle-AIron";
 var ARCHITECT_AGENT_ID = "agent-architect";
 var ARCHITECT_TEMPLATE_ID = "architect";
@@ -12363,21 +12369,21 @@ function buildCodeIndex(model) {
   const declarations = /* @__PURE__ */ new Map();
   const anchors = /* @__PURE__ */ new Map();
   const findingAnchors = /* @__PURE__ */ new Map();
-  const namesAt = (cache, path28, make) => {
-    const cached = cache.get(path28);
+  const namesAt = (cache, path29, make) => {
+    const cached = cache.get(path29);
     if (cached) return cached;
-    const f = facts.get(path28);
+    const f = facts.get(path29);
     if (!f) return NO_NAMES;
     const built = make(f);
-    cache.set(path28, built);
+    cache.set(path29, built);
     return built;
   };
   const republished = /* @__PURE__ */ new Map();
-  const republishedFrom = (path28) => {
-    const cached = republished.get(path28);
+  const republishedFrom = (path29) => {
+    const cached = republished.get(path29);
     if (cached) return cached;
-    const out = /* @__PURE__ */ new Set([path28]);
-    const queue = [path28];
+    const out = /* @__PURE__ */ new Set([path29]);
+    const queue = [path29];
     while (queue.length) {
       const from = queue.pop();
       const f = facts.get(from);
@@ -12390,7 +12396,7 @@ function buildCodeIndex(model) {
         }
       }
     }
-    republished.set(path28, out);
+    republished.set(path29, out);
     return out;
   };
   const NO_ORIGIN = /* @__PURE__ */ new Set();
@@ -12399,9 +12405,9 @@ function buildCodeIndex(model) {
     return to ? republishedFrom(to) : NO_ORIGIN;
   };
   const scopeOf = (site, from) => {
-    const path28 = pathKey(site.from ?? from);
-    const f = facts.get(path28);
-    return f?.status === "analyzed" && f.analysisGrade === "exact" ? { path: path28, facts: f } : void 0;
+    const path29 = pathKey(site.from ?? from);
+    const f = facts.get(path29);
+    return f?.status === "analyzed" && f.analysisGrade === "exact" ? { path: path29, facts: f } : void 0;
   };
   const originOf = (site, from) => {
     const resolved = scopeOf(site, from);
@@ -12440,14 +12446,14 @@ function buildCodeIndex(model) {
     if (site.via) for (const typeName of localTypesOf(f, site.via)) widenThroughType(typeName);
     return out;
   };
-  const declarationsAt = (path28) => namesAt(declarations, pathKey(path28), (f) => /* @__PURE__ */ new Set([...f.declaredNames, ...f.exportedNames]));
+  const declarationsAt = (path29) => namesAt(declarations, pathKey(path29), (f) => /* @__PURE__ */ new Set([...f.declaredNames, ...f.exportedNames]));
   return {
     paths,
     exactPaths,
-    factsAt: (path28) => facts.get(pathKey(path28)),
+    factsAt: (path29) => facts.get(pathKey(path29)),
     declarationsAt,
-    anchorsAt: (path28) => namesAt(anchors, pathKey(path28), (f) => /* @__PURE__ */ new Set([...f.declaredNames, ...f.exportedNames, ...f.anchoredNames])),
-    findingAnchorsAt: (path28) => namesAt(findingAnchors, pathKey(path28), (f) => new Set(f.anchoredNames)),
+    anchorsAt: (path29) => namesAt(anchors, pathKey(path29), (f) => /* @__PURE__ */ new Set([...f.declaredNames, ...f.exportedNames, ...f.anchoredNames])),
+    findingAnchorsAt: (path29) => namesAt(findingAnchors, pathKey(path29), (f) => new Set(f.anchoredNames)),
     originOf,
     possibleOriginsOf
   };
@@ -12485,10 +12491,10 @@ function buildRealizationIndex(ctx) {
   return {
     paths,
     implementationsOf: (compId) => implsByComponent.get(compId) ?? NONE_IMPL,
-    implementationsAt: (path28) => implsByPath.get(pathKey(path28)) ?? NONE_IMPL,
+    implementationsAt: (path29) => implsByPath.get(pathKey(path29)) ?? NONE_IMPL,
     filesOf: (compId) => filesByComponent.get(compId) ?? NONE_PATH,
     filesIn: (subsystemId) => filesBySubsystem.get(subsystemId) ?? NONE_PATH,
-    componentsAt: (path28) => componentsByPath.get(pathKey(path28)) ?? NONE_COMP
+    componentsAt: (path29) => componentsByPath.get(pathKey(path29)) ?? NONE_COMP
   };
 }
 function buildImportGraph(index, universe) {
@@ -12500,22 +12506,22 @@ function buildImportGraph(index, universe) {
       if (to && to !== from) into.add(to);
     }
   };
-  const importsOf = (path28) => {
-    const cached = imports.get(path28);
+  const importsOf = (path29) => {
+    const cached = imports.get(path29);
     if (cached) return cached;
-    const facts = index.factsAt(path28);
+    const facts = index.factsAt(path29);
     const out = /* @__PURE__ */ new Set();
-    if (facts?.status === "analyzed") resolveAll(path28, facts.imports, out);
-    imports.set(path28, out);
+    if (facts?.status === "analyzed") resolveAll(path29, facts.imports, out);
+    imports.set(path29, out);
     return out;
   };
-  const tracesOf = (path28) => {
-    const cached = traces.get(path28);
+  const tracesOf = (path29) => {
+    const cached = traces.get(path29);
     if (cached) return cached;
-    const facts = index.factsAt(path28);
-    const out = new Set(importsOf(path28));
-    if (facts?.status === "analyzed") resolveAll(path28, facts.reexports, out);
-    traces.set(path28, out);
+    const facts = index.factsAt(path29);
+    const out = new Set(importsOf(path29));
+    if (facts?.status === "analyzed") resolveAll(path29, facts.reexports, out);
+    traces.set(path29, out);
     return out;
   };
   return {
@@ -13826,11 +13832,11 @@ var unconditionalCallCyclesRule = {
       const memberEdges = keys.flatMap((k) => (adjacency.get(k) ?? []).filter((e) => inScc.has(e.toKey)));
       if (memberEdges.length === 0) continue;
       const anchor = [...memberEdges].sort((a, b) => byCodeUnit(a.fromKey, b.fromKey) || byCodeUnit(a.impl.id, b.impl.id) || a.stepNumber - b.stepNumber)[0];
-      const path28 = [...keys].sort(byCodeUnit).join(" \u2192 ");
+      const path29 = [...keys].sort(byCodeUnit).join(" \u2192 ");
       ctx.addIssue(
         "warning",
         "UNCONDITIONAL_CALL_CYCLE",
-        `Call cycle with no guard: ${path28} \u2014 every call edge in this cycle is unavoidable on all paths of its narrative (e.g. step ${anchor.stepNumber} of "${anchor.methodName}" in "${anchor.impl.id}" always calls ${anchor.toLabel}). This recurses without a base case, by construction. Guard at least one edge with a branch/return before the call, or lint.allow with the termination argument.`,
+        `Call cycle with no guard: ${path29} \u2014 every call edge in this cycle is unavoidable on all paths of its narrative (e.g. step ${anchor.stepNumber} of "${anchor.methodName}" in "${anchor.impl.id}" always calls ${anchor.toLabel}). This recurses without a base case, by construction. Guard at least one edge with a branch/return before the call, or lint.allow with the termination argument.`,
         anchor.impl.id,
         memberEdges.some((e) => ctx.isImplementationDraft(e.impl))
       );
@@ -16572,11 +16578,11 @@ var hiddenStateRule = {
         byPath.set(key, list);
       }
     }
-    for (const path28 of code.exactPaths) {
-      const facts = code.factsAt(path28);
+    for (const path29 of code.exactPaths) {
+      const facts = code.factsAt(path29);
       const bindings = facts.topLevelMutableBindings ?? [];
       if (bindings.length === 0) continue;
-      const mapped = byPath.get(path28) ?? [];
+      const mapped = byPath.get(path29) ?? [];
       if (mapped.length === 0) continue;
       if (!mapped.every((m) => isStatelessLogic(m.component))) continue;
       const anchor = [...mapped].sort((a, b) => a.impl.id.localeCompare(b.impl.id))[0];
@@ -16642,7 +16648,7 @@ var dependencyConformanceRule = {
       }
       return false;
     };
-    const draftAt = (path28) => realization.implementationsAt(path28).some((impl) => ctx.isImplementationDraft(impl));
+    const draftAt = (path29) => realization.implementationsAt(path29).some((impl) => ctx.isImplementationDraft(impl));
     for (const fromPath of mappedPaths) {
       const fromComponents = realization.componentsAt(fromPath);
       for (const toPath of graph.importsOf(fromPath)) {
@@ -22052,13 +22058,13 @@ function ineffectiveDeltaPaths(delta, merged, stored) {
   const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
   const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
   const at = (prefix, key) => prefix ? `${prefix}.${key}` : key;
-  const say = (path28, why) => {
-    out.push(`${path28} \u2014 ${why}`);
+  const say = (path29, why) => {
+    out.push(`${path29} \u2014 ${why}`);
   };
-  const walkValue = (d, m, s, path28, field) => {
+  const walkValue = (d, m, s, path29, field) => {
     if (Array.isArray(d)) {
       if (!Array.isArray(m)) {
-        say(path28, "the level does not have this field, so the write dropped it");
+        say(path29, "the level does not have this field, so the write dropped it");
         return;
       }
       if (field === "narrative" && d.some(carriesEditMarker)) return;
@@ -22066,32 +22072,32 @@ function ineffectiveDeltaPaths(delta, merged, stored) {
         if (carriesEditMarker(element)) continue;
         const key = reportIdentityOf(field, element);
         if (key === null) {
-          if (!same(m, d)) say(path28, "the level does not keep this value, so the write dropped it");
-          else if (same(s, d)) say(path28, "the stored spec already held this value");
+          if (!same(m, d)) say(path29, "the level does not keep this value, so the write dropped it");
+          else if (same(s, d)) say(path29, "the stored spec already held this value");
           return;
         }
         const mMatch = m.find((i) => reportIdentityOf(field, i) === key);
         const sMatch = Array.isArray(s) ? s.find((i) => reportIdentityOf(field, i) === key) : void 0;
         if (mMatch === void 0) {
-          say(at(path28, key), "the write did not store this element");
+          say(at(path29, key), "the write did not store this element");
           continue;
         }
-        walk2(element, mMatch, sMatch, at(path28, key), field);
+        walk2(element, mMatch, sMatch, at(path29, key), field);
       }
       return;
     }
     if (isPlain(d)) {
       if (!isPlain(m)) {
-        say(path28, "the level does not have this field, so the write dropped it");
+        say(path29, "the level does not have this field, so the write dropped it");
         return;
       }
-      walk2(d, m, s, path28, field);
+      walk2(d, m, s, path29, field);
       return;
     }
-    if (!same(m, d)) say(path28, "the write did not store it \u2014 the level's schema does not keep this value");
-    else if (same(s, d)) say(path28, "the stored spec already held this value");
+    if (!same(m, d)) say(path29, "the write did not store it \u2014 the level's schema does not keep this value");
+    else if (same(s, d)) say(path29, "the stored spec already held this value");
   };
-  function walk2(d, m, s, path28, container) {
+  function walk2(d, m, s, path29, container) {
     for (const [key, value] of Object.entries(d)) {
       if (DELTA_VERBS.has(key) || JUMP_LABEL_TWINS.has(key)) continue;
       if (key === "label" && LABEL_TWIN_CONTAINERS.has(container)) continue;
@@ -22101,13 +22107,13 @@ function ineffectiveDeltaPaths(delta, merged, stored) {
           if (typeof name !== "string") continue;
           const had = isPlain(s) && s[name] !== void 0;
           const still = isPlain(m) && m[name] !== void 0;
-          if (!had) say(at(path28, name), "unset named a field the stored spec did not have");
-          else if (still) say(at(path28, name), "unset did not remove it");
+          if (!had) say(at(path29, name), "unset named a field the stored spec did not have");
+          else if (still) say(at(path29, name), "unset did not remove it");
         }
         continue;
       }
       if (value === void 0 || value === null) continue;
-      const here = at(path28, key);
+      const here = at(path29, key);
       const mValue = isPlain(m) ? m[key] : void 0;
       const sValue = isPlain(s) ? s[key] : void 0;
       if (mValue === void 0) {
@@ -26341,12 +26347,24 @@ function readResource(resourceId) {
   return readSkillResource(resourceId);
 }
 
+// src/utils/ai-guide.ts
+var fs17 = __toESM(require("fs"));
+var os4 = __toESM(require("os"));
+var path22 = __toESM(require("path"));
+
 // src/core/stamp.ts
 function versionStamp() {
   return `<!-- wairon-version: ${WAIRON_VERSION} -->`;
 }
+var STAMP_RE = /<!--\s*wairon-version:\s*([^\s]+)\s*-->/;
+function readStampVersion(content) {
+  const m = content.match(STAMP_RE);
+  return m ? m[1] : null;
+}
 
 // src/utils/ai-guide.ts
+var GUIDE_MARKER_START = "<!-- wairon-guide-start -->";
+var GUIDE_MARKER_END = "<!-- wairon-guide-end -->";
 var GLOBAL_GUIDE_BODY = `## wairon \u2014 Spec-Driven Development (optional)
 
 If \`.wai/specs/\` exists, the wairon SDD workflow is active; otherwise ignore it. wairon does not orchestrate sessions \u2014 it equips yours.
@@ -26362,6 +26380,133 @@ If \`.wai/specs/\` exists, the wairon SDD workflow is active; otherwise ignore i
   5. **Design First**: Complete spec and pass \`sdd_validate_tree\` before writing code.
   6. **Consistency**: Code must match L3 interfaces and L5 narratives exactly. If the spec is wrong, stop and update the spec.
   7. **Subprojects & Namespacing**: If a subsystem uses \`projectPath\` delegation, target its specs using namespaced IDs (e.g. \`subsystem::component\`). Use leading \`::\` to target root (e.g. \`::shared::type\`) and \`super::\` to go up a level (e.g. \`super::sibling\`). wairon automatically resolves the path and strips the prefix on writes.`;
+var LOCAL_GUIDE_BODY = `## Wairon \u2014 Spec-Driven Development (you are operating inside it)
+
+This project uses **wairon**. System specs live under \`.wai/specs/\` (L0 System \u2192 L1 Subsystem \u2192 L2 Component \u2192 L3 Interface \u2192 L4 Implementation \u2192 Narrative); agent topology and code are derived from it.
+
+**Do NOT search files or read agent configs to learn about wairon or SDD. Use the context here and the \`sdd-architect\` skill to start.**
+
+**Your first move: call the \`sdd_get_status\` MCP tool** (or \`wairon/sdd_get_status\`) to see the spec tree. Do not parse files or run CLI commands manually.
+
+### How you operate
+- **To design/modify specs**: Use **\`sdd-architect\`** skill (in \`.claude/skills/\` or \`.gemini/skills/\`).
+- **Manage specs via MCP tools only**: Use \`sdd_initialize_system\`, \`sdd_add_subsystem\`, \`sdd_add_component\`, \`sdd_define_interface\`, \`sdd_write_narrative\`, \`sdd_add_type\`, \`sdd_get_spec\`, \`sdd_delete_spec\`, \`sdd_validate_tree\`, and \`sdd_get_status\` (namespaced if needed). Do not edit specs manually.
+- **Subprojects & Namespacing (Chaining)**: If a subsystem defines a \`projectPath\`, its entire \`.wai/\` spec tree is recursively loaded and namespaced with the subsystem ID as a prefix (using \`::\`, e.g. \`billing::invoice::invoice_portal\`). Use the qualified namespaced ID with the parent MCP tools; wairon will resolve the path and strip the prefix automatically.
+  - **Leading \`::\`**: Bypasses the local subsystem prefix to resolve absolute from the system root (e.g. \`::shared::error-type\`).
+  - **\`super::\`**: Goes up one parent subsystem level (e.g. \`super::sibling_comp\`, \`super::super::parent_sibling\`).
+- **Do not run the \`wairon\` CLI**: Use \`sdd_validate_tree\` and \`sdd_get_status\` instead of CLI commands.
+- **Handoff to implementation**: Once design is complete and validates cleanly, tell the human: *"The specs are complete and validate. Please run \`wairon lock\` to confirm and freeze them."* No session restart is needed after the lock \u2014 delegate implementation right away via the \`sdd-delegate\` skill.
+- **To implement code**: Delegate via the \`sdd-delegate\` skill: fetch the component's live brief with the \`sdd_get_agent_brief\` MCP tool (or the \`wairon-agent://\` resource) and spawn a subagent from it. Briefs are composed per call from the current spec tree, so they are always current \u2014 never wait for a restart. Implementations must match L3 interfaces and L5 narratives exactly. Generated agent files under \`.claude/agents/\` are an optional materialized view of the same topology \u2014 the live briefs are canonical.
+
+### Rules (enforced by \`sdd_validate_tree\`)
+1. **Design before code**: Complete spec and pass validator before writing source code.
+2. **Human-in-the-loop**: Ask user approval for each spec layer before proceeding.
+3. **Spec consistency**: If a 1:1 narrative match is incorrect or conflicts with L0 requirements, escalate a spec revision first. Never ship mismatched code.
+4. **No persistence shortcuts & strict layers**: A Portal must never depend directly on a Store, Registry, or Adapter. Portal reads MAY go through a Repository/Index facade (passthrough reads need no per-entity Orchestrator ceremony), but a Portal narrative call or dispatch-table binding that reaches a write-effect facade method is an error (\`PORTAL_WRITE_SHORTCUT\`) \u2014 writes always route through an Orchestrator. Held domain state always lives in a dedicated data component, never as fields inside an Orchestrator. Two sanctioned shapes: the RECOMMENDED Repository pattern (owns Store + Registry + Index; consumers depend on the facade), or \u2014 for genuinely simple state \u2014 a deliberately standalone Store (workflow-layer consumers only, acknowledged with a lint.allow reason on the UNOWNED_STORE warning). Never combine Store/Registry/Index roles into one component, and never fold state into a consuming component because a link was refused.
+
+### Component Vocabulary
+* **Blocks**: Portal, Orchestrator, Supervisor, Actor, Store, Index, Query, Registry, Adapter, Observer.
+* **Patterns**: Repository \u2014 the composable pattern that \`owns\` its member blocks: one Store with its Registry, Indexes and Queries, and optionally an Adapter.
+* **Variants**: \`gateway\`, a Portal that authenticates, authorizes, validates or rate-limits before it dispatches. Logic is an Orchestrator, and \`dependencyClass: pure | read\` bounds what it may depend on (unset = a workflow). Specialist and Gateway are retired stereotypes.
+* Use \`owns\` for private member containment (exactly one hop) and \`dependsOn\` for collaborators. Never use generic suffixes like "Manager", "Helper", or "Utils".`;
+function globalGuideFilePath(targetType) {
+  if (targetType === "claude") return path22.join(process.env["CLAUDE_CONFIG_DIR"] || path22.join(os4.homedir(), ".claude"), "CLAUDE.md");
+  if (targetType === "gemini") return path22.join(process.env["GEMINI_CONFIG_DIR"] || path22.join(os4.homedir(), ".gemini"), "GEMINI.md");
+  return null;
+}
+function localGuideFilePath(projectRoot, targetType) {
+  if (targetType === "claude") return path22.join(projectRoot, ".claude", "CLAUDE.md");
+  if (targetType === "gemini" || targetType === "agy") return path22.join(projectRoot, ".gemini", "GEMINI.md");
+  return null;
+}
+function injectGuide(filePath, scope) {
+  const body = scope === "global" ? GLOBAL_GUIDE_BODY : LOCAL_GUIDE_BODY;
+  const section = `
+
+${GUIDE_MARKER_START}
+${versionStamp()}
+${body}
+${GUIDE_MARKER_END}
+`;
+  const existing = fs17.existsSync(filePath) ? fs17.readFileSync(filePath, "utf-8") : "";
+  const stripped = stripGuideSection(existing);
+  const newContent = stripped.trimEnd() + section;
+  fs17.mkdirSync(path22.dirname(filePath), { recursive: true });
+  fs17.writeFileSync(filePath, newContent, "utf-8");
+}
+function stripGuideSection(content) {
+  const start = content.indexOf(GUIDE_MARKER_START);
+  const end = content.indexOf(GUIDE_MARKER_END);
+  if (start === -1 || end === -1) return content;
+  return content.slice(0, start) + content.slice(end + GUIDE_MARKER_END.length);
+}
+function writeRootGuideDelegator(projectRoot, targetType) {
+  if (targetType === "claude") {
+    const filePath = path22.join(projectRoot, "CLAUDE.md");
+    const content = `@.claude/CLAUDE.md
+
+# Wairon SDD Project
+
+This project uses the Wairon Spec-Driven Development (SDD) framework. The imported
+\`.claude/CLAUDE.md\` above is your complete operating guide \u2014 you already have the
+full context, so don't search the project to learn how wairon or SDD works.
+
+To design or modify the system, invoke the **\`sdd-architect\`** skill
+(in \`.claude/skills/\`). Author and validate specs with the \`sdd_*\` MCP tools;
+the \`wairon\` CLI is the human developer's tool, not yours.
+`;
+    fs17.writeFileSync(filePath, content, "utf-8");
+  } else if (targetType === "gemini" || targetType === "agy") {
+    const filePath = path22.join(projectRoot, "GEMINI.md");
+    const content = `# Wairon SDD Project
+${GUIDE_MARKER_START}
+${versionStamp()}
+${LOCAL_GUIDE_BODY}
+${GUIDE_MARKER_END}
+`;
+    fs17.writeFileSync(filePath, content, "utf-8");
+  } else if (targetType === "cursor") {
+    const filePath = path22.join(projectRoot, ".cursorrules");
+    const content = `# Wairon SDD Project
+
+This project uses the Wairon Spec-Driven Development (SDD) framework.
+
+Refer to the rules in [.cursor/rules/](.cursor/rules/) for full instructions.
+`;
+    fs17.writeFileSync(filePath, content, "utf-8");
+  } else if (targetType === "copilot") {
+    const filePath = path22.join(projectRoot, ".github", "copilot-instructions.md");
+    fs17.mkdirSync(path22.dirname(filePath), { recursive: true });
+    const content = `# Wairon SDD Project
+
+This project uses the Wairon Spec-Driven Development (SDD) framework.
+
+Refer to the prompts in [.github/prompts/](.github/prompts/) for instructions.
+`;
+    fs17.writeFileSync(filePath, content, "utf-8");
+  } else if (targetType === "codex") {
+    const filePath = path22.join(projectRoot, ".codexrules");
+    const content = `# Wairon SDD Project
+
+Refer to [.codex/agents/](.codex/agents/) for full instructions.
+`;
+    fs17.writeFileSync(filePath, content, "utf-8");
+  }
+}
+var GUIDE_TARGETS = ["claude", "gemini", "agy", "cursor", "copilot", "codex"];
+function reinjectLocalGuides(projectRoot, targetTypes) {
+  const written = [];
+  for (const type of targetTypes) {
+    if (!GUIDE_TARGETS.includes(type)) continue;
+    const guidePath = localGuideFilePath(projectRoot, type);
+    if (guidePath) {
+      injectGuide(guidePath, "local");
+      if (!written.includes(guidePath)) written.push(guidePath);
+    }
+    writeRootGuideDelegator(projectRoot, type);
+  }
+  return written;
+}
 
 // src/core/context.ts
 function contextDir(...segments) {
@@ -26496,8 +26641,8 @@ function syncContextFiles() {
 }
 
 // src/core/treetransfer.ts
-var fs17 = __toESM(require("fs"));
-var path22 = __toESM(require("path"));
+var fs18 = __toESM(require("fs"));
+var path23 = __toESM(require("path"));
 var sdkPortal = __toESM(require_dist());
 var STAGING_PREFIX = ".wai-staging-";
 var BACKUP_DIR = ".wai-backups";
@@ -26523,41 +26668,41 @@ function hasAuthoredSpecs(root) {
   if (!pathExists(specsDir)) {
     return false;
   }
-  const systemIndex = path22.resolve(paths.specsSystem());
+  const systemIndex = path23.resolve(paths.specsSystem());
   for (const file of listFilesRecursive(specsDir, ".yaml")) {
-    if (path22.resolve(file) !== systemIndex) {
+    if (path23.resolve(file) !== systemIndex) {
       return true;
     }
   }
   return false;
 }
 function createStagingDir(destDir) {
-  const root = path22.resolve(destDir);
-  fs17.mkdirSync(root, { recursive: true });
-  const stagingDir = fs17.mkdtempSync(path22.join(root, STAGING_PREFIX));
+  const root = path23.resolve(destDir);
+  fs18.mkdirSync(root, { recursive: true });
+  const stagingDir = fs18.mkdtempSync(path23.join(root, STAGING_PREFIX));
   return stagingDir;
 }
 function commitStagedTree(stagingDir, destDir, roots, backupExisting) {
-  const root = path22.resolve(destDir);
-  const backupDir = path22.join(root, BACKUP_DIR, timestampSlug());
+  const root = path23.resolve(destDir);
+  const backupDir = path23.join(root, BACKUP_DIR, timestampSlug());
   let backedUp = false;
   for (const rootRel of roots) {
     const relative9 = rootRel === "." ? "" : rootRel;
-    const stagedSpecDir = path22.join(stagingDir, relative9, ".wai");
-    if (!fs17.existsSync(stagedSpecDir)) continue;
-    const liveSpecDir = liveSpecDirFor(path22.join(root, relative9));
-    if (backupExisting && liveSpecDir && fs17.existsSync(liveSpecDir)) {
-      const backupTarget = path22.join(backupDir, relative9, path22.basename(liveSpecDir));
-      fs17.mkdirSync(path22.dirname(backupTarget), { recursive: true });
-      fs17.renameSync(liveSpecDir, backupTarget);
+    const stagedSpecDir = path23.join(stagingDir, relative9, ".wai");
+    if (!fs18.existsSync(stagedSpecDir)) continue;
+    const liveSpecDir = liveSpecDirFor(path23.join(root, relative9));
+    if (backupExisting && liveSpecDir && fs18.existsSync(liveSpecDir)) {
+      const backupTarget = path23.join(backupDir, relative9, path23.basename(liveSpecDir));
+      fs18.mkdirSync(path23.dirname(backupTarget), { recursive: true });
+      fs18.renameSync(liveSpecDir, backupTarget);
       backedUp = true;
-    } else if (liveSpecDir && fs17.existsSync(liveSpecDir)) {
-      fs17.rmSync(liveSpecDir, { recursive: true, force: true });
+    } else if (liveSpecDir && fs18.existsSync(liveSpecDir)) {
+      fs18.rmSync(liveSpecDir, { recursive: true, force: true });
     }
-    const target = path22.join(root, relative9, ".wai");
-    fs17.mkdirSync(path22.dirname(target), { recursive: true });
-    if (fs17.existsSync(target)) fs17.rmSync(target, { recursive: true, force: true });
-    fs17.renameSync(stagedSpecDir, target);
+    const target = path23.join(root, relative9, ".wai");
+    fs18.mkdirSync(path23.dirname(target), { recursive: true });
+    if (fs18.existsSync(target)) fs18.rmSync(target, { recursive: true, force: true });
+    fs18.renameSync(stagedSpecDir, target);
   }
   if (backedUp) {
     return backupDir;
@@ -26566,7 +26711,7 @@ function commitStagedTree(stagingDir, destDir, roots, backupExisting) {
 }
 function discardStagingDir(stagingDir) {
   try {
-    fs17.rmSync(stagingDir, { recursive: true, force: true });
+    fs18.rmSync(stagingDir, { recursive: true, force: true });
   } catch {
   }
 }
@@ -26580,7 +26725,7 @@ function exportSpecTree(includeDerived, allowPartial) {
   const skipped = [...inspection.skipped];
   const roots = [{ relativePath: ".", waiDir: aiPathsAt(root).root() }];
   for (const rel2 of inspection.roots) {
-    const waiDir = aiPathsAt(path22.resolve(root, rel2)).root();
+    const waiDir = aiPathsAt(path23.resolve(root, rel2)).root();
     if (pathExists(waiDir)) {
       roots.push({ relativePath: rel2, waiDir });
     } else {
@@ -26611,7 +26756,7 @@ function importSpecTree(archive, options) {
   if (!info.compatible) {
     throw new Error("incompatible .waitree archive (format or minimum wairon version)");
   }
-  const destDir = path22.resolve(options.destDir ?? getProjectRoot());
+  const destDir = path23.resolve(options.destDir ?? getProjectRoot());
   const occupied = hasSpecTree(destDir);
   const authored = hasAuthoredSpecs(destDir);
   if (authored && options.replaceExisting !== true) {
@@ -26642,10 +26787,10 @@ function importSpecTree(archive, options) {
   return result;
 }
 function liveSpecDirFor(rootDir) {
-  const modern = path22.join(rootDir, ".wai");
-  if (fs17.existsSync(modern)) return modern;
-  const legacy = path22.join(rootDir, ".wairon");
-  if (fs17.existsSync(legacy)) return legacy;
+  const modern = path23.join(rootDir, ".wai");
+  if (fs18.existsSync(modern)) return modern;
+  const legacy = path23.join(rootDir, ".wairon");
+  if (fs18.existsSync(legacy)) return legacy;
   return null;
 }
 function timestampSlug() {
@@ -26653,10 +26798,10 @@ function timestampSlug() {
 }
 
 // src/exporters/generate.ts
-var path26 = __toESM(require("path"));
+var path27 = __toESM(require("path"));
 
 // src/exporters/claude.ts
-var path23 = __toESM(require("path"));
+var path24 = __toESM(require("path"));
 var MODEL_BY_TIER = {
   small: "haiku",
   standard: "sonnet",
@@ -26695,7 +26840,7 @@ var ClaudeExporter = class {
   outputPath(ctx) {
     const { agent, target, projectRoot } = ctx;
     const outputDir = "outputDir" in target ? target.outputDir : ".claude/agents";
-    return path23.resolve(projectRoot, outputDir, `${agent.id.replace(/::/g, "--")}.md`);
+    return path24.resolve(projectRoot, outputDir, `${agent.id.replace(/::/g, "--")}.md`);
   }
   export(ctx) {
     const { agent, renderedInstructions, budget } = ctx;
@@ -26720,7 +26865,7 @@ var ClaudeExporter = class {
 };
 
 // src/exporters/custom.ts
-var path24 = __toESM(require("path"));
+var path25 = __toESM(require("path"));
 var CustomExporter = class {
   constructor() {
     this.targetType = "custom";
@@ -26730,7 +26875,7 @@ var CustomExporter = class {
     if (!("outputDir" in target)) {
       throw new Error("CustomExporter requires target.outputDir");
     }
-    return path24.resolve(projectRoot, target.outputDir, `${agent.id.replace(/::/g, "--")}.md`);
+    return path25.resolve(projectRoot, target.outputDir, `${agent.id.replace(/::/g, "--")}.md`);
   }
   export(ctx) {
     const { agent, target, renderedInstructions } = ctx;
@@ -26753,7 +26898,7 @@ var CustomExporter = class {
 };
 
 // src/exporters/gemini.ts
-var path25 = __toESM(require("path"));
+var path26 = __toESM(require("path"));
 var GeminiExporter = class {
   constructor() {
     this.targetType = "gemini";
@@ -26761,7 +26906,7 @@ var GeminiExporter = class {
   outputPath(ctx) {
     const { agent, target, projectRoot } = ctx;
     const outputDir = "outputDir" in target ? target.outputDir : ".gemini/agents";
-    return path25.resolve(projectRoot, outputDir, `${agent.id.replace(/::/g, "--")}.yaml`);
+    return path26.resolve(projectRoot, outputDir, `${agent.id.replace(/::/g, "--")}.yaml`);
   }
   export(ctx) {
     const { agent, renderedInstructions } = ctx;
@@ -26858,7 +27003,7 @@ function resolveExpectedOutputPaths(agents, projectConfig, projectRoot = getProj
       const targetConfig = resolveTargetConfig(agentTarget, projectConfig);
       if (!targetConfig) continue;
       const ctx = { agent, projectRoot, target: targetConfig };
-      expected.add(path26.resolve(getExporter(targetConfig).outputPath(ctx)));
+      expected.add(path27.resolve(getExporter(targetConfig).outputPath(ctx)));
     }
   }
   return expected;
@@ -27005,7 +27150,7 @@ function repairForeignStepFields(apply) {
 
 // src/core/approval.ts
 var crypto4 = __toESM(require("crypto"));
-var path27 = __toESM(require("path"));
+var path28 = __toESM(require("path"));
 function diffSize(d) {
   return d.added.length + d.changed.length + d.removed.length;
 }
@@ -27014,12 +27159,12 @@ function digest(content) {
   return crypto4.createHash("sha256").update(normalized, "utf8").digest("hex");
 }
 function currentSpecDigests(root = getProjectRoot()) {
-  const mountDirs = loadSubsystemSpecs().filter((s) => s.projectPath && !s.id.includes("::")).map((s) => `${path27.resolve(root, s.projectPath).split(path27.sep).join("/")}/`);
+  const mountDirs = loadSubsystemSpecs().filter((s) => s.projectPath && !s.id.includes("::")).map((s) => `${path28.resolve(root, s.projectPath).split(path28.sep).join("/")}/`);
   const out = {};
   for (const [abs, content] of snapshotSpecFiles()) {
-    const normalized = path27.resolve(abs).split(path27.sep).join("/");
+    const normalized = path28.resolve(abs).split(path28.sep).join("/");
     if (mountDirs.some((dir) => normalized.startsWith(dir))) continue;
-    out[path27.relative(root, abs).split(path27.sep).join("/")] = digest(content);
+    out[path28.relative(root, abs).split(path28.sep).join("/")] = digest(content);
   }
   return out;
 }
@@ -27077,7 +27222,7 @@ function currentChildPins(mounts, root = getProjectRoot()) {
   const pins = {};
   for (const mount of mounts) {
     if (!mount.projectPath || mount.id.includes("::")) continue;
-    const child = readLockRecordAt(path27.resolve(root, mount.projectPath));
+    const child = readLockRecordAt(path28.resolve(root, mount.projectPath));
     if (child) pins[mount.id] = pinOf(child.stateId);
   }
   return pins;
@@ -27096,7 +27241,7 @@ function movedChildren(mounts, root = getProjectRoot()) {
 
 // src/core/approver.ts
 var import_child_process = require("child_process");
-var os4 = __toESM(require("os"));
+var os5 = __toESM(require("os"));
 function gitConfig(key) {
   try {
     const value = (0, import_child_process.execFileSync)("git", ["config", "--get", key], {
@@ -27112,12 +27257,12 @@ function gitConfig(key) {
 function machineIdentity() {
   let user = "unknown";
   try {
-    user = os4.userInfo().username || user;
+    user = os5.userInfo().username || user;
   } catch {
   }
   let host = "";
   try {
-    host = os4.hostname();
+    host = os5.hostname();
   } catch {
   }
   return { id: host ? `${user}@${host}` : user, source: "os" };
@@ -27454,6 +27599,7 @@ function loadProjectConfig4() {
   getSubprojectPrefix,
   getSubsystemPath,
   getTypePath,
+  globalGuideFilePath,
   globalPacksDir,
   globalPacksEnabled,
   globalTemplatesDir,
@@ -27470,6 +27616,7 @@ function loadProjectConfig4() {
   importSpecTree,
   importSurface,
   ineffectiveDeltaPaths,
+  injectGuide,
   inspectChainedRoots,
   inspectTreeArchive,
   installPackFromDirectory,
@@ -27523,6 +27670,7 @@ function loadProjectConfig4() {
   loadTypeSpec,
   loadTypeSpecs,
   localApprover,
+  localGuideFilePath,
   localTypesOf,
   logger,
   makeScopeFilter,
@@ -27565,12 +27713,14 @@ function loadProjectConfig4() {
   readProjectContext,
   readResource,
   readSkillResource,
+  readStampVersion,
   readYamlFile,
   rebaseProjectVariants,
   rebaseReference,
   recordProfileSelection,
   registerExporter,
   registerPackRef,
+  reinjectLocalGuides,
   removeDomain,
   removePackSelection,
   removeSnapshot,
@@ -27648,6 +27798,7 @@ function loadProjectConfig4() {
   writeJsonFile,
   writeLockRecord,
   writeProjectContext,
+  writeRootGuideDelegator,
   writeYamlFile
 });
 //# sourceMappingURL=index.js.map