specrails-core 4.8.1 → 4.9.0

package/dist/installer/phases/scaffold.js

@@ -1,7 +1,10 @@
+import { createHash } from 'node:crypto';
 import { rmSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { copyDir, copyFile, isDir, listDir, mkdirp, pathExists, readTextFile, writeFileLf } from '../util/fs.js';
+import { atomicSymlinkSwap, copyDir, copyFile, isDir, isSymlink, listDir, mkdirp, pathExists, readTextFile, removePath, symlinkOrCopy, writeFileLf, } from '../util/fs.js';
 import { info, ok, warn } from '../util/logger.js';
+import { buildManifest, writeManifestFiles } from './manifest.js';
 /**
  * The three baseline agents that every specrails install requires.
  * These are the only agents guaranteed to be present — the implement
@@ -26,8 +29,50 @@ const QUICK_EXCLUDED_AGENTS = new Set(['sr-product-manager', 'sr-product-analyst
  * (Validated headless in the desktop spike — read/write/shell/glob/grep.) Because
  * gemini TOML commands cannot carry per-command tool/model routing, the tool +
  * model gating migrates into the subagent frontmatter.
+ *
+ * `activate_skill` is mandatory: the architect/developer/reviewer personas open
+ * with a NON-NEGOTIABLE OpenSpec skill call (`opsx:ff`/`apply`/`archive`). Gemini
+ * exposes skills through the `activate_skill` tool — without it in the tools list
+ * the agent halts with "the required `Skill` tool is not available" and the only
+ * way the pipeline ever completed was the orchestrator hand-patching the agent
+ * file mid-run. See `translateOpsxSkillCallsForGemini` for the body half.
+ */
+const GEMINI_AGENT_TOOLS = ['read_file', 'write_file', 'run_shell_command', 'glob', 'search_file_content', 'activate_skill'];
+/**
+ * Claude `Skill("opsx:<id>")` → Gemini `activate_skill(name="<skill>")` id map.
+ * The agent persona templates are authored in Claude form (the shared source of
+ * truth across providers); Gemini invokes the same OpenSpec workflow skills under
+ * a different tool name and skill-directory names. The mapping is NOT a uniform
+ * `-change` suffix (`sync` → `*-sync-specs`, `explore`/`onboard` have none), so it
+ * must be explicit. Keys mirror the skill directories scaffolded under
+ * `.gemini/skills/openspec-*`.
+ */
+const OPSX_TO_GEMINI_SKILL = {
+    ff: 'openspec-ff-change',
+    new: 'openspec-new-change',
+    apply: 'openspec-apply-change',
+    continue: 'openspec-continue-change',
+    archive: 'openspec-archive-change',
+    'bulk-archive': 'openspec-bulk-archive-change',
+    sync: 'openspec-sync-specs',
+    verify: 'openspec-verify-change',
+    explore: 'openspec-explore',
+    onboard: 'openspec-onboard',
+};
+/**
+ * Rewrite every literal `Skill("opsx:<id>"[, …])` call in a Claude-authored agent
+ * body into the Gemini `activate_skill(name="…")` form. Positional skill input
+ * (e.g. `"<specName>"`) is dropped because `activate_skill` takes only `name` and
+ * the surrounding persona prose already carries the context. Unknown ids are left
+ * untouched (better a visible stale ref than a silent `name="undefined"`). This
+ * runs ONLY on the gemini render path; Claude/Codex keep the `Skill(...)` form.
  */
-const GEMINI_AGENT_TOOLS = ['read_file', 'write_file', 'run_shell_command', 'glob', 'search_file_content'];
+export function translateOpsxSkillCallsForGemini(body) {
+    return body.replace(/Skill\("opsx:([a-z-]+)"(?:\s*,[^)]*)?\)/g, (match, id) => {
+        const skill = OPSX_TO_GEMINI_SKILL[id];
+        return skill ? `activate_skill(name="${skill}")` : match;
+    });
+}
 /**
  * Per-role gemini model. Defaults to `gemini-3.5-flash` — the stable flagship
  * (June 2026): strong agentic/coding, high quota, and unlike `gemini-2.5-pro`
@@ -40,6 +85,15 @@ const GEMINI_MODEL_BY_AGENT = {
     'sr-reviewer': 'gemini-3.5-flash',
 };
 const GEMINI_DEFAULT_MODEL = 'gemini-3.5-flash';
+// NOTE: do NOT emit a `max_turns` (or `maxTurns`/`runConfig`) key in the gemini
+// agent frontmatter. Although gemini's documented agent schema lists `max_turns`,
+// the 0.46 runtime loader REJECTS a `.gemini/agents/*.md` file that carries it —
+// the agent silently fails to register and `invoke_agent` reports "Subagent
+// '<name>' not found", so the orchestrator falls back to a generic agent and the
+// specialised personas never run. Verified empirically (two identical agents,
+// one with `max_turns: 40` → not found, one without → loads). The 30-turn default
+// cap is instead absorbed by the implement.toml MAX_TURNS → re-delegate/resume
+// contract. Re-introduce only if a future gemini build is reconfirmed to accept it.
 /**
  * Skills excluded from the quick tier because they depend on
  * VPC-only agents (sr-product-manager, sr-product-analyst).
@@ -103,6 +157,21 @@ const COMMAND_AGENT_DEPENDENCIES = [
  * directory alongside the per-agent memory dirs.
  */
 const EXPLANATION_AUTHORS = new Set(['sr-architect', 'sr-reviewer']);
+/**
+ * Provider-static subtrees inside a providerDir that are SHARED via symlink from
+ * the framework copy into each workspace. `agent-memory/` is deliberately absent
+ * — it is mutable per-workspace state seeded as a real dir, never linked.
+ *
+ * The root instruction file (`CLAUDE.md`/`AGENTS.md`/`GEMINI.md`) and the codex
+ * `config.toml` / gemini `settings.json` carry the project name / a deep-merge
+ * with the user's file, so they are SEEDED per-workspace (not linked) by
+ * `assembleProjectWorkspace`.
+ */
+const LINKED_PROVIDER_SUBTREES = {
+    claude: ['agents', 'commands', 'skills', 'rules'],
+    codex: ['skills'],
+    gemini: ['agents', 'commands'],
+};
 /**
  * Returns true iff any of the provider directories already contains
  * content. The desktop-app-driven path skips the "merge existing?" prompt and
@@ -111,10 +180,11 @@ const EXPLANATION_AUTHORS = new Set(['sr-architect', 'sr-reviewer']);
  */
 export function detectExistingSetup(input) {
     const roots = [
-        path.join(input.repoRoot, input.providerDir, 'agents'),
-        path.join(input.repoRoot, input.providerDir, 'commands'),
-        path.join(input.repoRoot, input.providerDir, 'rules'),
-        path.join(input.repoRoot, 'openspec'),
+        path.join(input.artifactRoot, input.providerDir, 'agents'),
+        path.join(input.artifactRoot, input.providerDir, 'commands'),
+        path.join(input.artifactRoot, input.providerDir, 'rules'),
+        // openspec stays in the repo (codeRoot), not the relocated artifact root.
+        path.join(input.codeRoot, 'openspec'),
     ];
     for (const r of roots) {
         if (isDir(r) && listDir(r).length > 0)
@@ -134,26 +204,26 @@ export function scaffoldInstallation(input) {
         createdDirs.push(abs);
     };
     // --- Directory skeleton ---
-    mk(path.join(input.repoRoot, input.providerDir));
+    mk(path.join(input.artifactRoot, input.providerDir));
     if (input.provider === 'codex') {
         // Codex skills live under <providerDir>/skills/ (e.g. .codex/skills/).
         // The pre-§18 code wrote to `.agents/skills/` which codex doesn't read;
         // that was a placeholder name from the gated state.
-        mk(path.join(input.repoRoot, input.providerDir, 'skills', 'enrich'));
-        mk(path.join(input.repoRoot, input.providerDir, 'skills', 'doctor'));
-        mk(path.join(input.repoRoot, input.providerDir, 'skills', 'rails'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'enrich'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'doctor'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'skills', 'rails'));
     }
     else if (input.provider === 'gemini') {
         // Gemini: TOML commands under .gemini/commands/specrails/ + native
         // subagents under .gemini/agents/. No skills/ tree.
-        mk(path.join(input.repoRoot, input.providerDir, 'commands', 'specrails'));
-        mk(path.join(input.repoRoot, input.providerDir, 'agents'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'agents'));
     }
     else {
-        mk(path.join(input.repoRoot, input.providerDir, 'commands', 'specrails'));
-        mk(path.join(input.repoRoot, input.providerDir, 'skills'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails'));
+        mk(path.join(input.artifactRoot, input.providerDir, 'skills'));
     }
-    const setupTemplates = path.join(input.repoRoot, '.specrails', 'setup-templates');
+    const setupTemplates = path.join(input.artifactRoot, '.specrails', 'setup-templates');
     mk(path.join(setupTemplates, 'agents'));
     mk(path.join(setupTemplates, 'commands'));
     mk(path.join(setupTemplates, 'skills'));
@@ -162,10 +232,16 @@ export function scaffoldInstallation(input) {
     mk(path.join(setupTemplates, 'claude-md'));
     mk(path.join(setupTemplates, 'settings'));
     // --- .gitignore hygiene ---
-    const gitignoreEntries = ['.claude/agent-memory/', '.specrails/'];
-    if (input.provider === 'gemini')
-        gitignoreEntries.push('.gemini/agent-memory/');
-    ensureGitignore(input.repoRoot, gitignoreEntries);
+    // Under relocate-always (artifactRoot !== codeRoot) NOTHING Specrails-owned
+    // lands in the repo, so there is nothing to ignore — the gitignore step is a
+    // guarded no-op. It only runs in the legacy in-repo layout where the two roots
+    // coincide.
+    if (input.artifactRoot === input.codeRoot) {
+        const gitignoreEntries = ['.claude/agent-memory/', '.specrails/'];
+        if (input.provider === 'gemini')
+            gitignoreEntries.push('.gemini/agent-memory/');
+        ensureGitignore(input.codeRoot, gitignoreEntries);
+    }
     // --- Copy bundled templates into setup-templates/ ---
     const templatesSrc = path.join(input.scriptDir, 'templates');
     if (pathExists(templatesSrc)) {
@@ -234,13 +310,362 @@ export function scaffoldInstallation(input) {
     ok(`Created ${createdDirs.length} directories, copied ${copiedFiles} files`);
     return {
         existingSetup: detectExistingSetup({
-            repoRoot: input.repoRoot,
+            artifactRoot: input.artifactRoot,
+            codeRoot: input.codeRoot,
             providerDir: input.providerDir,
         }),
         createdDirs,
         copiedFiles,
     };
 }
+/** Path to the per-version, per-provider materialization marker (manifest hash). */
+function frameworkStampPath(versionDir, providerDir) {
+    // Store the stamp OUTSIDE the providerDir so it never leaks into the linked
+    // subtree. `.stamp-<providerDir>.json` is provider-keyed.
+    return path.join(versionDir, `.framework-stamp${providerDir}.json`);
+}
+/**
+ * Materialize the provider-INVARIANT framework subtree ONCE into
+ * `<frameworkDir>/<version>/<providerDir>/` (+ `<version>/setup-templates/`).
+ * Idempotent: when the providerDir already exists with a matching stamp it is a
+ * no-op (the second workspace assemble re-uses the same copy). Writes NO
+ * per-workspace state (no agent-memory, no acks, no project-named instruction
+ * files) — those are seeded by `assembleProjectWorkspace`.
+ */
+export function installFramework(input) {
+    const versionDir = path.join(input.frameworkDir, input.version);
+    const providerFrameworkDir = path.join(versionDir, input.providerDir);
+    const stampPath = frameworkStampPath(versionDir, input.providerDir);
+    // Idempotency: existing materialization with a matching stamp → skip.
+    if (isDir(providerFrameworkDir) && pathExists(stampPath)) {
+        return { providerFrameworkDir, versionDir, materialized: false };
+    }
+    // Reuse scaffoldInstallation's static-placement helpers by pointing
+    // `artifactRoot` at the version dir. `seedProjectDirs: false` keeps the copy
+    // free of per-workspace mutable state. The `codeRoot` is irrelevant to the
+    // STATIC subtree (the project-named instruction files are skipped below), so
+    // we hand it the framework dir to satisfy the contract — and we DELETE any
+    // project-named instruction file the settings helpers wrote.
+    // The SHARED framework store is always the FULL SUPERSET — EVERY agent and the
+    // team commands — so a SECOND project with a DIFFERENT agent selection links
+    // its specialists from the same materialized copy instead of inheriting the
+    // first project's narrower set. Per-project filtering moves to the workspace
+    // LINK step (`linkAgentFiles` via `assembleProjectWorkspace`). `selectedAgents`
+    // / `agentTeams` on the input are intentionally IGNORED here.
+    const staticInput = {
+        scriptDir: input.scriptDir,
+        artifactRoot: versionDir,
+        codeRoot: versionDir,
+        provider: input.provider,
+        providerDir: input.providerDir,
+        agentTeams: true,
+        tier: 'quick',
+        selectedAgents: undefined,
+        materializeAllAgents: true,
+        seedProjectDirs: false,
+    };
+    scaffoldInstallation(staticInput);
+    // The settings helpers also emit a project-named root instruction file
+    // (AGENTS.md/GEMINI.md/CLAUDE.md) + (for codex) config.toml / (gemini)
+    // settings.json. The instruction file is per-project → strip it from the
+    // shared copy; the settings file IS provider-invariant and stays as a
+    // link target inside the providerDir.
+    for (const f of ['AGENTS.md', 'GEMINI.md', 'CLAUDE.md']) {
+        rmSync(path.join(versionDir, f), { force: true });
+    }
+    writeFileLf(stampPath, `${JSON.stringify({ version: input.version, provider: input.provider, at: new Date().toISOString() }, null, 2)}\n`);
+    return { providerFrameworkDir, versionDir, materialized: true };
+}
+/**
+ * Atomically point `<frameworkDir>/current` at `<version>` so every workspace's
+ * provider links resolve through `current/...` and an update is a single swap.
+ */
+export function ensureCurrentSymlink(frameworkDir, version) {
+    const currentPath = path.join(frameworkDir, 'current');
+    const versionDir = path.join(frameworkDir, version);
+    mkdirp(frameworkDir);
+    atomicSymlinkSwap(versionDir, currentPath);
+}
+/**
+ * Assemble a project workspace with NO network and NO re-materialization: (a)
+ * SYMLINK the static providerDir subtrees from `<frameworkDir>/current/
+ * <providerDir>/` into `<workspace>/<providerDir>/`, then (b) seed the PROJECT
+ * layer as real writable files (agent-memory dirs, the manifest, project-named
+ * instruction/settings files, gemini headless acks re-hashed against the LINKED
+ * files). `agent-memory/` is NEVER linked.
+ */
+export function assembleProjectWorkspace(input) {
+    const currentProviderDir = path.join(input.frameworkDir, 'current', input.providerDir);
+    const workspaceProviderDir = path.join(input.workspace, input.providerDir);
+    mkdirp(workspaceProviderDir);
+    // (a) Link the static subtrees that exist in the framework copy.
+    //
+    // `agents/` is linked PER-FILE (a real workspace dir holding one symlink per
+    // framework agent) so the workspace can also carry user/desktop `custom-*.md`
+    // agents — a RESERVED region the installer must never touch. Every other
+    // subtree (`commands/`, `skills/`, `rules/`) holds no user files and is linked
+    // as a whole directory (cheapest, single inode).
+    // Per-project AGENT selection: link only the selected framework agents (∪ the
+    // CORE trio, minus the quick-excluded product agents) — the shared store holds
+    // the full superset, so a project's narrower pick links a SUBSET. Undefined ⇒
+    // CORE trio only. `custom-*.md` is always preserved (reserved path).
+    const selectedAgentSet = input.selectedAgents
+        ? new Set([...input.selectedAgents, ...CORE_AGENTS])
+        : new Set([...CORE_AGENTS]);
+    const agentTeams = input.agentTeams ?? false;
+    const links = {};
+    for (const sub of LINKED_PROVIDER_SUBTREES[input.provider]) {
+        const target = path.join(currentProviderDir, sub);
+        if (!pathExists(target))
+            continue;
+        const dest = path.join(workspaceProviderDir, sub);
+        if (sub === 'agents') {
+            links[sub] = linkAgentFiles(target, dest, selectedAgentSet);
+        }
+        else if (!agentTeams && subtreeHasTeamEntries(target)) {
+            // Lean install AND the superset store actually carries `team-*` entries:
+            // link this subtree PER-FILE, excluding the team commands/skills. The
+            // common case (no team-* in the store) keeps the cheap whole-dir symlink
+            // below — preserving the single-inode contract.
+            links[sub] = linkSubtreeExcludingTeams(target, dest);
+        }
+        else {
+            links[sub] = symlinkOrCopy(target, dest);
+        }
+    }
+    // Link the provider-invariant settings file (codex config.toml / gemini
+    // settings.json) when the framework has one and the user has not authored a
+    // local override in the workspace.
+    const settingsFile = input.provider === 'codex' ? 'config.toml' : input.provider === 'gemini' ? 'settings.json' : null;
+    if (settingsFile) {
+        const settingsTarget = path.join(currentProviderDir, settingsFile);
+        const settingsLink = path.join(workspaceProviderDir, settingsFile);
+        if (pathExists(settingsTarget) && !pathExists(settingsLink)) {
+            links[settingsFile] = symlinkOrCopy(settingsTarget, settingsLink);
+        }
+    }
+    // (b) Seed the PROJECT layer (real writable files / dirs).
+    const seededMemoryAgents = seedProjectLayer(input, currentProviderDir);
+    // Manifest: record the consumed framework version. `buildManifest` hashes the
+    // package's templates/ + commands (provenance), written under the workspace.
+    const manifest = buildManifest({
+        scriptDir: input.scriptDir,
+        repoRoot: input.workspace,
+        version: input.version,
+    });
+    writeManifestFiles(input.workspace, manifest);
+    return { links, seededMemoryAgents };
+}
+/**
+ * Seed the per-workspace PROJECT layer: real agent-memory dirs (+ explanations/),
+ * the project-named instruction file, and — for gemini — the headless
+ * acknowledgments re-hashed against the LINKED agent files. Returns the agent
+ * ids whose memory dirs were created.
+ */
+function seedProjectLayer(input, currentProviderDir) {
+    const selected = input.selectedAgents
+        ? new Set([...input.selectedAgents, ...CORE_AGENTS])
+        : new Set([...CORE_AGENTS]);
+    // Discover which agents the framework actually placed (so memory dirs match
+    // the linked agent set), intersected with the selection.
+    const agentsLinkDir = path.join(currentProviderDir, 'agents');
+    const placedAgentIds = [];
+    if (isDir(agentsLinkDir)) {
+        for (const entry of listDir(agentsLinkDir)) {
+            const name = path.basename(entry);
+            if (!name.endsWith('.md'))
+                continue;
+            const id = name.slice(0, -3);
+            if (selected.has(id) && !QUICK_EXCLUDED_AGENTS.has(id))
+                placedAgentIds.push(id);
+        }
+    }
+    const seededMemoryAgents = [];
+    if (input.provider === 'claude') {
+        for (const id of placedAgentIds) {
+            mkdirp(path.join(input.workspace, '.claude', 'agent-memory', id));
+            seededMemoryAgents.push(id);
+            if (EXPLANATION_AUTHORS.has(id)) {
+                mkdirp(path.join(input.workspace, '.claude', 'agent-memory', 'explanations'));
+            }
+        }
+    }
+    else if (input.provider === 'gemini') {
+        for (const id of placedAgentIds) {
+            mkdirp(path.join(input.workspace, '.gemini', 'agent-memory', id));
+            seededMemoryAgents.push(id);
+        }
+    }
+    // Project-named instruction file (codex AGENTS.md / gemini GEMINI.md). Reuse
+    // the same sentinel-upsert helpers via the settings appliers, scoped so they
+    // ONLY emit the instruction file (the settings file is already linked above).
+    if (input.provider === 'codex') {
+        seedInstructionFile(path.join(input.workspace, 'AGENTS.md'), renderInitialAgentsMd(input.codeRoot));
+    }
+    else if (input.provider === 'gemini') {
+        seedInstructionFile(path.join(input.workspace, 'GEMINI.md'), renderInitialGeminiMd(input.codeRoot));
+        // Gemini headless acks: hash the LINKED agent files (read through the
+        // symlink) keyed on the real repo so `gemini -p` trusts them with no prompt.
+        try {
+            writeGeminiAgentAcknowledgments(input.codeRoot, placedAgentIds, input.workspace);
+        }
+        catch (err) {
+            warn(`gemini agent pre-acknowledgment skipped: ${err.message}`);
+        }
+    }
+    return seededMemoryAgents;
+}
+/**
+ * Per-file link the framework `agents/` into a REAL workspace `agents/` dir.
+ * Keeps `custom-*.md` (and any other user-authored file that the framework does
+ * NOT provide) byte-untouched — the reserved-paths contract — while pointing
+ * every SELECTED framework-owned agent at the shared read-only copy.
+ *
+ * `selectedIds` is the per-project agent allow-list (already unioned with the
+ * CORE trio by the caller). Only framework agents whose id is in it AND not in
+ * `QUICK_EXCLUDED_AGENTS` are linked — the shared framework store is the full
+ * superset, so this is where per-project filtering lands. `undefined` ⇒ link
+ * every framework agent (used by the legacy callers / parity tests).
+ *
+ * Returns the dominant mechanism used across the linked files (`copy` if any
+ * file fell back to copy — the normal case on Windows without Developer Mode).
+ */
+function linkAgentFiles(frameworkAgentsDir, workspaceAgentsDir, selectedIds) {
+    mkdirp(workspaceAgentsDir);
+    // Names the framework currently PROVIDES (regardless of selection) — used to
+    // distinguish a framework-owned file from a user `custom-*.md` during cleanup.
+    const frameworkProvided = new Set();
+    // Names actually LINKED this pass (the selected subset).
+    const linkedNames = new Set();
+    let mechanism = 'symlink';
+    for (const src of listDir(frameworkAgentsDir)) {
+        const name = path.basename(src);
+        if (!name.endsWith('.md'))
+            continue;
+        frameworkProvided.add(name);
+        const id = name.slice(0, -3);
+        if (selectedIds && (!selectedIds.has(id) || QUICK_EXCLUDED_AGENTS.has(id)))
+            continue;
+        linkedNames.add(name);
+        const m = symlinkOrCopy(src, path.join(workspaceAgentsDir, name));
+        if (m === 'copy')
+            mechanism = 'copy';
+        else if (m === 'junction' && mechanism !== 'copy')
+            mechanism = 'junction';
+    }
+    // Drop STALE framework artifacts in the workspace agents dir — both prior-
+    // version symlinks AND copy-fallback files (Windows) that are no longer linked
+    // this pass (a dropped agent, or one deselected). NEVER remove a user file:
+    // `custom-*.md` and agent-memory are reserved. The discriminator is "the
+    // framework owns this name (it's currently provided OR it was a previous
+    // framework link/copy that the framework no longer provides)" — we approximate
+    // it as: remove any entry NOT in `linkedNames` that is either a symlink (old
+    // framework link) OR a NON-custom framework-shaped file the framework once
+    // provided. `custom-*.md` is always skipped.
+    for (const existing of listDir(workspaceAgentsDir)) {
+        const name = path.basename(existing);
+        if (linkedNames.has(name))
+            continue;
+        if (name.startsWith('custom-'))
+            continue; // reserved user agent — never touch
+        if (isSymlink(existing)) {
+            // A prior framework symlink no longer selected/provided → stale, drop it.
+            removePath(existing);
+            continue;
+        }
+        // A copy-fallback framework file (Windows): a non-symlink `.md` that the
+        // framework provides (or provided) but is not a user custom agent. Remove it
+        // so a version swap or a deselect cleans up the copied agent. Files the
+        // framework never provided (genuine user agents) are left untouched.
+        if (name.endsWith('.md') && (frameworkProvided.has(name) || isFrameworkAgentName(name))) {
+            removePath(existing);
+        }
+    }
+    return mechanism;
+}
+/**
+ * True when `name` (an `<id>.md`) matches a framework-owned agent id (`sr-*`).
+ * Used to identify a stale COPY-fallback framework agent on Windows that the
+ * current framework version no longer provides, so it can be cleaned up on a
+ * version swap. `custom-*.md` (handled by the caller) and any non-`sr-` user
+ * file are deliberately excluded.
+ */
+function isFrameworkAgentName(name) {
+    return /^sr-[a-z0-9-]+\.md$/.test(name);
+}
+/**
+ * True when a framework subtree (`commands`/`skills`) contains any `team-*`
+ * entry (a `team-*.md` file or a `team-*` skill dir), recursively. Gates the
+ * per-file team-excluding link path: when no team entries exist the workspace
+ * keeps the cheap whole-dir symlink. Recurses into real subdirs (e.g.
+ * `.claude/commands/specrails/`).
+ */
+function subtreeHasTeamEntries(subtreeDir) {
+    for (const entry of listDir(subtreeDir)) {
+        const name = path.basename(entry);
+        if (/^team-/.test(name) || /^team-/.test(name.replace(/\.md$/, '')))
+            return true;
+        if (isDir(entry) && !isSymlink(entry) && subtreeHasTeamEntries(entry))
+            return true;
+    }
+    return false;
+}
+/**
+ * Link a whole framework subtree (`commands`/`skills`) into the workspace
+ * PER-FILE, EXCLUDING the Agent-Teams `team-*` entries. Used when `agentTeams`
+ * is off and the shared framework store (always the superset) carries the team
+ * commands the lean install must not surface. Recurses into subdirs (e.g.
+ * `.claude/commands/specrails/`). Returns the dominant mechanism.
+ */
+function linkSubtreeExcludingTeams(frameworkSubtreeDir, workspaceSubtreeDir) {
+    mkdirp(workspaceSubtreeDir);
+    let mechanism = 'symlink';
+    const bump = (m) => {
+        if (m === 'copy')
+            mechanism = 'copy';
+        else if (m === 'junction' && mechanism !== 'copy')
+            mechanism = 'junction';
+    };
+    const linkedNames = new Set();
+    for (const src of listDir(frameworkSubtreeDir)) {
+        const name = path.basename(src);
+        // Exclude team commands/skills whether they ship as `team-*.md` files or
+        // `team-*/` skill dirs.
+        if (/^team-/.test(name) || /^team-/.test(name.replace(/\.md$/, '')))
+            continue;
+        linkedNames.add(name);
+        const dest = path.join(workspaceSubtreeDir, name);
+        if (isDir(src) && !isSymlink(src)) {
+            // Recurse: a real framework subdir is mirrored as a real workspace subdir
+            // so a future agentTeams=false re-link can prune team-* inside it too.
+            bump(linkSubtreeExcludingTeams(src, dest));
+        }
+        else {
+            bump(symlinkOrCopy(src, dest));
+        }
+    }
+    // Drop stale framework entries (including team-* left from a prior agentTeams
+    // run) that are no longer linked. Only symlinks/copied framework files — there
+    // are no user files under commands/skills.
+    for (const existing of listDir(workspaceSubtreeDir)) {
+        const name = path.basename(existing);
+        if (linkedNames.has(name))
+            continue;
+        removePath(existing);
+    }
+    return mechanism;
+}
+/** Write or sentinel-upsert a project instruction file (AGENTS.md/GEMINI.md). */
+function seedInstructionFile(filePath, content) {
+    if (!pathExists(filePath)) {
+        writeFileLf(filePath, content);
+        return;
+    }
+    const existing = readTextFile(filePath);
+    const next = upsertAgentsMdManagedBlock(existing, extractManagedBlock(content));
+    if (next !== existing)
+        writeFileLf(filePath, next);
+}
 function copyBundledCommands(input) {
     const commandsSrc = path.join(input.scriptDir, 'commands');
     if (!isDir(commandsSrc))
@@ -261,7 +686,7 @@ function copyBundledCommands(input) {
             if (!input.agentTeams && /^team-/.test(name))
                 continue;
             const skillName = name.replace(/\.md$/, '');
-            const destDir = path.join(input.repoRoot, input.providerDir, 'skills', skillName);
+            const destDir = path.join(input.artifactRoot, input.providerDir, 'skills', skillName);
             // A codex-native override (written for spawn_agent semantics + the
             // correct `.codex/skills/rails/` layout) wins over the claude port.
             // This is the ONLY codex command-placement pass in full tier, so
@@ -286,7 +711,7 @@ function copyBundledCommands(input) {
     if (input.provider === 'gemini') {
         // Gemini: each bundled command becomes a TOML custom command under
         // .gemini/commands/specrails/<name>.toml.
-        const destDir = path.join(input.repoRoot, input.providerDir, 'commands', 'specrails');
+        const destDir = path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails');
         let count = 0;
         for (const entry of listDir(commandsSrc)) {
             const name = path.basename(entry);
@@ -306,7 +731,7 @@ function copyBundledCommands(input) {
         return;
     }
     // Claude: all bundled commands land under <providerDir>/commands/specrails/.
-    const destDir = path.join(input.repoRoot, input.providerDir, 'commands', 'specrails');
+    const destDir = path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails');
     let count = 0;
     for (const entry of listDir(commandsSrc)) {
         const name = path.basename(entry);
@@ -476,12 +901,14 @@ function writeGeminiAgentFromTemplate(args) {
         '---',
         '',
     ].join('\n');
-    const renderedBody = renderPlaceholders(body, {
+    const renderedBody = translateOpsxSkillCallsForGemini(renderPlaceholders(body, {
         ...args.placeholders,
         MEMORY_PATH: `.gemini/agent-memory/${args.agentId}/`,
-    }).replace(/\.claude\//g, '.gemini/');
-    writeFileLf(path.join(args.repoRoot, '.gemini', 'agents', `${args.agentId}.md`), frontmatter + renderedBody);
-    mkdirp(path.join(args.repoRoot, '.gemini', 'agent-memory', args.agentId));
+    }).replace(/\.claude\//g, '.gemini/'));
+    writeFileLf(path.join(args.artifactRoot, '.gemini', 'agents', `${args.agentId}.md`), frontmatter + renderedBody);
+    if (args.seedProjectDirs !== false) {
+        mkdirp(path.join(args.artifactRoot, '.gemini', 'agent-memory', args.agentId));
+    }
 }
 /**
  * Place the gemini subagents under `.gemini/agents/` from the staged persona
@@ -489,35 +916,112 @@ function writeGeminiAgentFromTemplate(args) {
  */
 function placeGeminiAgents(input) {
     const result = { placed: 0, skipped: 0, filesCopied: 0 };
-    const agentsSrc = path.join(input.repoRoot, '.specrails', 'setup-templates', 'agents');
+    const agentsSrc = path.join(input.artifactRoot, '.specrails', 'setup-templates', 'agents');
     if (!isDir(agentsSrc))
         return result;
-    mkdirp(path.join(input.repoRoot, '.gemini', 'agents'));
+    mkdirp(path.join(input.artifactRoot, '.gemini', 'agents'));
     const selectedAgents = input.selectedAgents
         ? new Set([...input.selectedAgents, ...CORE_AGENTS])
         : new Set([...CORE_AGENTS]);
     const placeholders = {
-        PROJECT_NAME: path.basename(input.repoRoot),
+        PROJECT_NAME: path.basename(input.codeRoot),
         SECURITY_EXEMPTIONS_PATH: '.gemini/security-exemptions.yaml',
         PERSONA_DIR: '.gemini/agents/personas/',
     };
+    const placedIds = [];
     for (const src of listDir(agentsSrc)) {
         const name = path.basename(src);
         if (!name.endsWith('.md'))
             continue;
         const agentId = name.slice(0, -3);
-        if (!selectedAgents.has(agentId))
+        // Superset materialization (installFramework) places EVERY agent; per-project
+        // filtering happens at the workspace LINK step (linkAgentFiles).
+        if (!input.materializeAllAgents && !selectedAgents.has(agentId))
             continue;
-        if (QUICK_EXCLUDED_AGENTS.has(agentId)) {
+        if (!input.materializeAllAgents && QUICK_EXCLUDED_AGENTS.has(agentId)) {
             result.skipped++;
             continue;
         }
-        writeGeminiAgentFromTemplate({ repoRoot: input.repoRoot, src, agentId, placeholders });
+        writeGeminiAgentFromTemplate({
+            artifactRoot: input.artifactRoot,
+            src,
+            agentId,
+            placeholders,
+            seedProjectDirs: input.seedProjectDirs,
+        });
+        placedIds.push(agentId);
         result.placed++;
         result.filesCopied++;
     }
+    // The pre-acknowledgment is a PER-WORKSPACE seed (keyed on codeRoot, hashing the
+    // workspace's linked agent files). It is skipped when materializing the shared
+    // framework — `assembleProjectWorkspace` re-writes it against the LINKED files.
+    if (input.seedProjectDirs !== false) {
+        try {
+            // Key the acknowledgment on the real repo (codeRoot) so gemini matches the
+            // project, but hash the agent files from the relocated artifactRoot.
+            writeGeminiAgentAcknowledgments(input.codeRoot, placedIds, input.artifactRoot);
+        }
+        catch (err) {
+            warn(`gemini agent pre-acknowledgment skipped: ${err.message}`);
+        }
+    }
     return result;
 }
+/**
+ * Pre-acknowledge the generated gemini subagents so they load in HEADLESS
+ * (`gemini -p`) runs. gemini 0.46+ DISCOVERS `.gemini/agents/*.md` but only
+ * ENABLES a project's custom agents after the interactive "New Agents Discovered
+ * → Acknowledge and Enable" prompt — which never fires headless, so
+ * `invoke_agent sr-architect` returns "Subagent not found" and the implement
+ * orchestrator silently falls back to a generic agent (the specialised personas
+ * never run, the pipeline degrades). The acknowledgment is a user-global file
+ * `~/.gemini/acknowledgments/agents.json` shaped
+ * `{ [projectRoot]: { [agentName]: <sha256-hex of the agent .md file> } }`
+ * (hash algorithm verified empirically against gemini 0.47 = sha256 of the full
+ * file). Writing it at install time makes the freshly-generated agents trusted
+ * with no prompt, for both `gemini` CLI and the desktop's headless spawns. The
+ * file is MERGED — other projects' and other agents' entries are preserved.
+ * Best-effort: any failure is swallowed by the caller (agents still work once
+ * acknowledged interactively).
+ */
+export function writeGeminiAgentAcknowledgments(repoRoot, agentIds, agentsBaseDir = repoRoot) {
+    if (agentIds.length === 0)
+        return;
+    const ackPath = path.join(os.homedir(), '.gemini', 'acknowledgments', 'agents.json');
+    let store = {};
+    if (pathExists(ackPath)) {
+        try {
+            const parsed = JSON.parse(readTextFile(ackPath));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                store = parsed;
+            }
+        }
+        catch {
+            // Corrupt/unreadable file — start fresh rather than crash the install.
+        }
+    }
+    // The store is KEYED on `agentsBaseDir` — the directory gemini ACTUALLY runs
+    // in when it resolves the project's agents. Under relocation the linked agents
+    // live in the WORKSPACE (rails spawn with cwd=workspace), so the ack must be
+    // keyed on the workspace providerDir base, not the repo; otherwise headless
+    // `gemini -p` looks up `store[<workspace>]`, finds nothing, and the specialised
+    // personas never load. The agent FILES are hashed from `agentsBaseDir` too
+    // (read through the workspace symlinks ⇒ framework file content). When
+    // `agentsBaseDir` defaults to `repoRoot` (legacy in-repo layout, 2-arg call)
+    // the key is byte-identical to before.
+    const ackKey = agentsBaseDir;
+    const projectEntry = { ...(store[ackKey] ?? {}) };
+    for (const agentId of agentIds) {
+        const agentFile = path.join(agentsBaseDir, '.gemini', 'agents', `${agentId}.md`);
+        if (!pathExists(agentFile))
+            continue;
+        projectEntry[agentId] = createHash('sha256').update(readTextFile(agentFile)).digest('hex');
+    }
+    store[ackKey] = projectEntry;
+    mkdirp(path.dirname(ackPath));
+    writeFileLf(ackPath, `${JSON.stringify(store, null, 2)}\n`);
+}
 /** Recursive JSON object merge; source wins on scalars/arrays. */
 function deepMergeJson(target, source) {
     const out = { ...target };
@@ -541,7 +1045,7 @@ function applyGeminiSettings(input) {
     let written = 0;
     const settingsSrc = path.join(input.scriptDir, 'templates', 'settings', 'gemini-settings.json');
     if (pathExists(settingsSrc)) {
-        const dest = path.join(input.repoRoot, input.providerDir, 'settings.json');
+        const dest = path.join(input.artifactRoot, input.providerDir, 'settings.json');
         const template = JSON.parse(readTextFile(settingsSrc));
         if (pathExists(dest)) {
             try {
@@ -558,8 +1062,10 @@ function applyGeminiSettings(input) {
             written++;
         }
     }
-    const geminiMdPath = path.join(input.repoRoot, 'GEMINI.md');
-    const content = renderInitialGeminiMd(input.repoRoot);
+    const geminiMdPath = path.join(input.artifactRoot, 'GEMINI.md');
+    // Project name in the rendered body derives from the real repo (codeRoot),
+    // while the file itself lands under the relocated artifactRoot.
+    const content = renderInitialGeminiMd(input.codeRoot);
     if (!pathExists(geminiMdPath)) {
         writeFileLf(geminiMdPath, content);
         written++;
@@ -600,30 +1106,40 @@ function renderInitialGeminiMd(repoRoot) {
 }
 function pruneLegacyArtifacts(input) {
     const legacyPaths = [
-        path.join(input.repoRoot, '.specrails', 'bin', 'doctor.sh'),
-        path.join(input.repoRoot, '.specrails', 'setup-templates', '.provider-detection.json'),
-        path.join(input.repoRoot, '.specrails', 'setup-templates', 'settings', 'integration-contract.json'),
-        path.join(input.repoRoot, '.specrails-version'),
+        path.join(input.artifactRoot, '.specrails', 'bin', 'doctor.sh'),
+        path.join(input.artifactRoot, '.specrails', 'setup-templates', '.provider-detection.json'),
+        path.join(input.artifactRoot, '.specrails', 'setup-templates', 'settings', 'integration-contract.json'),
+        path.join(input.artifactRoot, '.specrails-version'),
     ];
     if (input.provider === 'codex') {
         // Pre-§18 layout used `.agents/skills/` — prune any leftovers from a
         // legacy install before settling on the canonical `.codex/skills/`.
-        legacyPaths.push(path.join(input.repoRoot, '.agents'));
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'skills', 'setup'));
+        legacyPaths.push(path.join(input.artifactRoot, '.agents'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'skills', 'setup'));
     }
     else if (input.provider === 'gemini') {
         // Prune a stale WIP skills/ tree + any setup command leftovers.
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'skills'));
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'commands', 'setup.toml'));
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'commands', 'specrails', 'setup.toml'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'skills'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'setup.toml'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails', 'setup.toml'));
     }
     else {
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'commands', 'setup.md'));
-        legacyPaths.push(path.join(input.repoRoot, input.providerDir, 'commands', 'specrails', 'setup.md'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'setup.md'));
+        legacyPaths.push(path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails', 'setup.md'));
     }
+    // Safety invariant: every prune target MUST live inside artifactRoot. Under
+    // relocate-always artifactRoot is the $HOME workspace, so this guarantees the
+    // installer never rmSync's anything inside the user's repo (codeRoot).
+    const artifactRootResolved = path.resolve(input.artifactRoot);
     for (const target of legacyPaths) {
+        const resolved = path.resolve(target);
+        const rel = path.relative(artifactRootResolved, resolved);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+            warn(`refusing to prune ${target} — outside artifactRoot ${input.artifactRoot}`);
+            continue;
+        }
         try {
-            rmSync(target, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
+            rmSync(resolved, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
         }
         catch (err) {
             warn(`failed to prune legacy artifact ${target}: ${err.message}`);
@@ -652,7 +1168,7 @@ function placeQuickTierArtefacts(input) {
     // command surface (`propose-spec`, `explore-spec`, `retry`, …) as
     // claude.
     if (input.provider === 'codex') {
-        const setupTemplates = path.join(input.repoRoot, '.specrails', 'setup-templates');
+        const setupTemplates = path.join(input.artifactRoot, '.specrails', 'setup-templates');
         const commandsSrc = path.join(setupTemplates, 'commands', 'specrails');
         // Codex-native skill overrides live at `templates/codex-skills/<name>/`.
         // When one exists for a given slash-command name (e.g. `implement`), the
@@ -672,7 +1188,7 @@ function placeQuickTierArtefacts(input) {
                 if (!input.agentTeams && /^team-/.test(name))
                     continue;
                 const skillName = name.slice(0, -3);
-                const dest = path.join(input.repoRoot, input.providerDir, 'skills', skillName, 'SKILL.md');
+                const dest = path.join(input.artifactRoot, input.providerDir, 'skills', skillName, 'SKILL.md');
                 // If a codex-native override exists, ship it verbatim and skip the
                 // ported claude body entirely. Mirrors a directory copy in case the
                 // override ships sibling assets.
@@ -698,7 +1214,7 @@ function placeQuickTierArtefacts(input) {
         // <name>.toml. Hand-authored orchestrator overrides (implement,
         // batch-implement) under templates/gemini-commands/ win verbatim. Agents
         // are placed by placeSkills → placeGeminiAgents (both tiers).
-        const geminiSetupTemplates = path.join(input.repoRoot, '.specrails', 'setup-templates');
+        const geminiSetupTemplates = path.join(input.artifactRoot, '.specrails', 'setup-templates');
         const commandsSrc = path.join(geminiSetupTemplates, 'commands', 'specrails');
         const overridesSrc = path.join(input.scriptDir, 'templates', 'gemini-commands');
         let commandsPlaced = 0;
@@ -712,7 +1228,7 @@ function placeQuickTierArtefacts(input) {
                 if (!input.agentTeams && /^team-/.test(name))
                     continue;
                 const cmdName = name.slice(0, -3);
-                const dest = path.join(input.repoRoot, input.providerDir, 'commands', 'specrails', `${cmdName}.toml`);
+                const dest = path.join(input.artifactRoot, input.providerDir, 'commands', 'specrails', `${cmdName}.toml`);
                 const overrideToml = path.join(overridesSrc, `${cmdName}.toml`);
                 if (pathExists(overrideToml)) {
                     copyFile(overrideToml, dest);
@@ -725,9 +1241,10 @@ function placeQuickTierArtefacts(input) {
         }
         return { agents: 0, commands: commandsPlaced, rules: 0, skippedAgents: 0 };
     }
-    const setupTemplates = path.join(input.repoRoot, '.specrails', 'setup-templates');
-    const projectName = path.basename(input.repoRoot);
-    const providerDirAbs = path.join(input.repoRoot, input.providerDir);
+    const setupTemplates = path.join(input.artifactRoot, '.specrails', 'setup-templates');
+    // PROJECT_NAME is the real repo's basename, not the relocated workspace dir.
+    const projectName = path.basename(input.codeRoot);
+    const providerDirAbs = path.join(input.artifactRoot, input.providerDir);
     const placeholders = {
         PROJECT_NAME: projectName,
         SECURITY_EXEMPTIONS_PATH: `${input.providerDir}/security-exemptions.yaml`,
@@ -753,9 +1270,12 @@ function placeQuickTierArtefacts(input) {
             if (!name.endsWith('.md'))
                 continue;
             const agentId = name.slice(0, -3);
-            if (selectedAgents && !selectedAgents.has(agentId))
+            // Superset materialization (installFramework) places EVERY agent so any
+            // project's selection can later link from the shared store; per-project
+            // filtering happens at the workspace LINK step, not here.
+            if (!input.materializeAllAgents && selectedAgents && !selectedAgents.has(agentId))
                 continue;
-            if (QUICK_EXCLUDED_AGENTS.has(agentId)) {
+            if (!input.materializeAllAgents && QUICK_EXCLUDED_AGENTS.has(agentId)) {
                 agentsSkipped++;
                 continue;
             }
@@ -767,11 +1287,16 @@ function placeQuickTierArtefacts(input) {
             writeFileLf(dest, rendered);
             agentsPlaced++;
             installedAgentNames.add(agentId);
-            // Per-agent memory directory. Created even when empty so
-            // the first run of the agent doesn't error on ENOENT.
-            mkdirp(path.join(input.repoRoot, '.claude', 'agent-memory', agentId));
-            if (EXPLANATION_AUTHORS.has(agentId)) {
-                mkdirp(path.join(input.repoRoot, '.claude', 'agent-memory', 'explanations'));
+            // Per-agent memory directory. Created even when empty so the first run of
+            // the agent doesn't error on ENOENT. Skipped when materializing the SHARED
+            // framework (`seedProjectDirs === false`): agent-memory is per-workspace
+            // mutable state seeded later by `seedProjectLayer`, NEVER part of the
+            // read-only framework copy that workspaces symlink.
+            if (input.seedProjectDirs !== false) {
+                mkdirp(path.join(input.artifactRoot, '.claude', 'agent-memory', agentId));
+                if (EXPLANATION_AUTHORS.has(agentId)) {
+                    mkdirp(path.join(input.artifactRoot, '.claude', 'agent-memory', 'explanations'));
+                }
             }
         }
     }
@@ -844,7 +1369,7 @@ function applyCodexSettings(input) {
     // reasoning_effort etc.
     const configTomlSrc = path.join(settingsSrc, 'codex-config.toml');
     if (pathExists(configTomlSrc)) {
-        const dest = path.join(input.repoRoot, input.providerDir, 'config.toml');
+        const dest = path.join(input.artifactRoot, input.providerDir, 'config.toml');
         const rendered = readTextFile(configTomlSrc).replace(/\{\{MODEL_NAME\}\}/g, 'gpt-5.5-mini');
         writeFileLf(dest, rendered);
         written++;
@@ -852,8 +1377,8 @@ function applyCodexSettings(input) {
     // AGENTS.md — top-level instructions file the codex CLI loads on startup.
     // Written with a sentinel block so update + enrich passes can refresh the
     // managed content while preserving anything the user added outside it.
-    const agentsMdPath = path.join(input.repoRoot, 'AGENTS.md');
-    const agentsMdContent = renderInitialAgentsMd(input.repoRoot);
+    const agentsMdPath = path.join(input.artifactRoot, 'AGENTS.md');
+    const agentsMdContent = renderInitialAgentsMd(input.codeRoot);
     if (!pathExists(agentsMdPath)) {
         writeFileLf(agentsMdPath, agentsMdContent);
         written++;
@@ -927,11 +1452,11 @@ function upsertAgentsMdManagedBlock(existing, managedBlock) {
 // `subagent_type` calls have no codex equivalent). Codex DOES get the rails
 // subtree below, sourced from `templates/codex-skills/rails/`.
 function placeSkills(input) {
-    const destBase = path.join(input.repoRoot, input.providerDir, 'skills');
+    const destBase = path.join(input.artifactRoot, input.providerDir, 'skills');
     const result = { placed: 0, skipped: 0, filesCopied: 0 };
     // Top-level skills — Claude only, generated from the canonical command body.
     if (input.provider === 'claude') {
-        const commandsSrc = path.join(input.repoRoot, '.specrails', 'setup-templates', 'commands', 'specrails');
+        const commandsSrc = path.join(input.artifactRoot, '.specrails', 'setup-templates', 'commands', 'specrails');
         const skillEntries = Object.entries(SKILL_FROM_COMMAND);
         for (const [skillName, spec] of skillEntries) {
             if (input.tier === 'quick' && QUICK_EXCLUDED_SKILLS.has(skillName)) {