specrails-core 4.8.2 → 4.9.1

package/dist/installer/util/registry.js

@@ -0,0 +1,339 @@
+/**
+ * Shared artifact registry — the contract that lets specrails-core place,
+ * and specrails-desktop read, a repo's relocated artifacts OUTSIDE the repo,
+ * under `$HOME/.specrails/projects/<slug>/workspace`.
+ *
+ * Single source of truth: `$HOME/.specrails/registry.json`, an inspectable,
+ * schema-versioned JSON file keyed by the **canonical realpath of the repo**.
+ * specrails-desktop is the primary writer (a projection of its `desktop.sqlite`);
+ * specrails-core reads it and, when run standalone, allocates its own entry.
+ *
+ * Design contract: `docs/internals/global-artifacts-alignment-contract.md`
+ * (in the specrails-desktop repo). The slug algorithm, canonical-key rule,
+ * atomic-write rule and lock protocol here MUST stay byte-identical to the
+ * desktop-side implementation — the correctness of the cross-tool contract
+ * depends on both tools resolving the same repo to the same paths.
+ *
+ * Everything in this module is synchronous to fit the installer's sync flow.
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** Registry schema version. A reader that sees a higher value MUST treat all
+ *  entries as absent (legacy fallback), never mis-parse. */
+export const REGISTRY_SCHEMA_VERSION = 1;
+/**
+ * Slug derivation — byte-identical to specrails-desktop's `slugify`
+ * (`server/desktop-router.ts`). Do not "improve" it; parity is the contract.
+ */
+export function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/** `$HOME` for the registry, overridable for tests. */
+export function resolveHome(home) {
+    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os.homedir();
+}
+/** Absolute path to `registry.json`. */
+export function registryPath(home) {
+    return path.join(resolveHome(home), '.specrails', 'registry.json');
+}
+/**
+ * Absolute path to the versioned framework store
+ * (`<home>/.specrails/framework`). The bundled-framework split materializes the
+ * provider-invariant subtree to `<frameworkDir>/<version>/<providerDir>/` once
+ * and every workspace symlinks `<frameworkDir>/current/<providerDir>/...`. Shares
+ * the SAME home as the registry so framework, registry, and workspaces co-locate
+ * (and tests pinning `SPECRAILS_REGISTRY_HOME` redirect all three together).
+ */
+export function frameworkRoot(home) {
+    return path.join(resolveHome(home), '.specrails', 'framework');
+}
+/** Absolute path to the advisory lock file. */
+export function lockPath(home) {
+    return registryPath(home) + '.lock';
+}
+/** `fs.realpathSync` that falls back to the resolved-but-unreal path on error
+ *  (the path may not exist yet, or be on a volume that rejects realpath). */
+export function realpathSafe(abs) {
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** Case-fold the key on case-insensitive platforms (macOS, Windows) so two
+ *  spellings of the same path map to one entry. The stored `repoPath` keeps
+ *  its canonical case; only the index key is folded. */
+export function normalizeKey(canon) {
+    if (process.platform === 'darwin' || process.platform === 'win32') {
+        return canon.toLowerCase();
+    }
+    return canon;
+}
+/** Canonical repo path: resolve to absolute, then realpath (collapses symlinks). */
+export function canonicalizeRepoPath(repoPathInput) {
+    return realpathSafe(path.resolve(repoPathInput));
+}
+/** The per-project sub-path layout under a workspace dir. Single source of the
+ *  layout so writer and (allocation) reader never disagree. */
+export function workspaceLayout(home, slug, canon) {
+    const workspaceDir = path.join(resolveHome(home), '.specrails', 'projects', slug, 'workspace');
+    const specrailsDir = path.join(workspaceDir, '.specrails');
+    return {
+        repoPath: canon,
+        slug,
+        workspaceDir,
+        artifactRoot: workspaceDir,
+        codeRoot: canon,
+        stateDir: path.join(workspaceDir, '.claude'),
+        ticketsPath: path.join(specrailsDir, 'local-tickets.json'),
+        backlogConfigPath: path.join(specrailsDir, 'backlog-config.json'),
+        profilesDir: path.join(specrailsDir, 'profiles'),
+        pluginsStateDir: path.join(specrailsDir, 'plugins'),
+        fileSummariesDir: path.join(specrailsDir, 'file-summaries'),
+    };
+}
+/** The in-repo layout, used when there is no registry entry (legacy fallback). */
+export function legacyResolution(canon) {
+    const specrailsDir = path.join(canon, '.specrails');
+    return {
+        key: normalizeKey(canon),
+        repoPath: canon,
+        slug: '',
+        workspaceDir: canon,
+        artifactRoot: canon,
+        codeRoot: canon,
+        stateDir: path.join(canon, '.claude'),
+        ticketsPath: path.join(specrailsDir, 'local-tickets.json'),
+        backlogConfigPath: path.join(specrailsDir, 'backlog-config.json'),
+        profilesDir: path.join(specrailsDir, 'profiles'),
+        pluginsStateDir: path.join(specrailsDir, 'plugins'),
+        fileSummariesDir: path.join(specrailsDir, 'file-summaries'),
+        providers: [],
+        primaryProvider: '',
+        source: 'legacy',
+        isLegacy: true,
+    };
+}
+/** Flatten a stored entry into a Resolution. */
+export function entryToResolution(key, entry) {
+    return {
+        key,
+        repoPath: entry.repoPath,
+        slug: entry.slug,
+        workspaceDir: entry.workspaceDir,
+        artifactRoot: entry.artifactRoot,
+        codeRoot: entry.codeRoot,
+        stateDir: entry.stateDir,
+        ticketsPath: entry.ticketsPath,
+        backlogConfigPath: entry.backlogConfigPath,
+        profilesDir: entry.profilesDir,
+        pluginsStateDir: entry.pluginsStateDir,
+        fileSummariesDir: entry.fileSummariesDir,
+        providers: entry.providers,
+        primaryProvider: entry.primaryProvider,
+        source: entry.source,
+        isLegacy: false,
+    };
+}
+/**
+ * Total, fail-open read. A missing file, a parse error, or a `schemaVersion`
+ * greater than we understand all yield an empty registry, so a caller treats
+ * it as "no entry" and (if allocating) writes a fresh, understood entry rather
+ * than crashing. Biases toward availability over strict consistency — correct
+ * for a local, inspectable file.
+ */
+export function readRegistryOrEmpty(home) {
+    const empty = { schemaVersion: REGISTRY_SCHEMA_VERSION, projects: {} };
+    const p = registryPath(home);
+    if (!existsSync(p))
+        return empty;
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            typeof parsed.schemaVersion !== 'number' ||
+            parsed.schemaVersion > REGISTRY_SCHEMA_VERSION ||
+            typeof parsed.projects !== 'object' ||
+            parsed.projects === null) {
+            return empty;
+        }
+        return parsed;
+    }
+    catch {
+        return empty;
+    }
+}
+/** Write `data` to `filePath` atomically: temp file in the same dir, fsync,
+ *  rename. A reader (even without the lock) only ever sees a complete old or
+ *  new file — the lock serialises writers, the rename protects readers. */
+export function atomicWrite(filePath, data) {
+    const dir = path.dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    // Deterministic-but-unique temp name (no Math.random/Date dependency for the
+    // name itself); collisions are impossible because the lock serialises writers.
+    const tmp = path.join(dir, `.${path.basename(filePath)}.tmp-${process.pid}`);
+    const fd = openSync(tmp, 'w');
+    try {
+        writeFileSync(fd, data);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, filePath);
+}
+/** Synchronous sleep without busy-spinning the CPU. */
+function syncSleep(ms) {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_SPIN_MS = 50;
+const LOCK_MAX_WAIT_MS = 2_000;
+/**
+ * Run `fn` while holding an advisory lock over the registry. Mutual exclusion
+ * is an exclusive-create lock file (`open(..., 'wx')`) with bounded spin-retry
+ * and stale-lock breaking (a lock whose mtime exceeds the TTL is reclaimed —
+ * covers a crashed writer). Read-only callers never take the lock.
+ */
+export function withFileLock(home, fn) {
+    const lp = lockPath(home);
+    mkdirSync(path.dirname(lp), { recursive: true });
+    let fd;
+    // Unique per-acquisition token written INTO the lock file. On release we only
+    // unlink the file when the token still matches OURS — so a writer whose lock
+    // was stale-broken (TTL-reclaimed) by another writer never deletes the NEW
+    // owner's lock out from under it (which would let a third writer acquire
+    // concurrently and race the read-modify-write).
+    const ourToken = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const deadline = Date.now() + LOCK_MAX_WAIT_MS;
+    for (;;) {
+        try {
+            fd = openSync(lp, 'wx');
+            try {
+                writeFileSync(fd, ourToken);
+                fsyncSync(fd);
+            }
+            catch {
+                /* best-effort — the lock still serialises via exclusive-create */
+            }
+            break;
+        }
+        catch {
+            // Lock held — break it if stale, otherwise spin until the deadline.
+            try {
+                const age = Date.now() - statSync(lp).mtimeMs;
+                if (age > LOCK_STALE_MS) {
+                    unlinkSync(lp);
+                    continue;
+                }
+            }
+            catch {
+                // lock vanished between open and stat — retry immediately
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                // FAIL CLOSED: proceeding without the lock would run `fn()` (a
+                // read-modify-write of the registry) with NO exclusivity, so a
+                // concurrent core+desktop writer can lost-update the registry. Throw
+                // instead of silently dropping mutual exclusivity — callers wrap this as
+                // non-fatal (the registry update is retried / skipped).
+                throw new Error('registry lock acquisition timed out');
+            }
+            syncSleep(LOCK_SPIN_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* already closed */
+            }
+            // Only unlink the lock when it still carries OUR token. If we were
+            // stale-broken and another writer now owns the file, its token differs and
+            // we leave it alone (a missing/unreadable file ⇒ already gone ⇒ no-op).
+            try {
+                const onDisk = readFileSync(lp, 'utf8');
+                if (onDisk === ourToken) {
+                    unlinkSync(lp);
+                }
+            }
+            catch {
+                /* already removed / unreadable — nothing to clean up */
+            }
+        }
+    }
+}
+/** Deterministic slug allocation: basename-derived, `-N` dedup suffix. Both
+ *  tools implement this identically so they only ever diverge on the suffix,
+ *  which read-before-allocate resolves. */
+export function allocateSlug(canon, existing) {
+    let base = slugify(path.basename(canon));
+    if (base === '')
+        base = 'project';
+    if (!existing.has(base))
+        return base;
+    let n = 2;
+    while (existing.has(`${base}-${n}`))
+        n += 1;
+    return `${base}-${n}`;
+}
+function buildEntry(home, canon, slug, opts) {
+    const providers = opts.providers && opts.providers.length > 0 ? opts.providers : ['claude'];
+    const now = opts.now ?? new Date().toISOString();
+    const layout = workspaceLayout(home, slug, canon);
+    const entry = {
+        ...layout,
+        providers,
+        primaryProvider: providers[0],
+        coreVersion: opts.coreVersion,
+        createdAt: now,
+        lastInstallAt: now,
+        source: opts.allocator ?? 'core-standalone',
+    };
+    if (opts.desktopProjectId)
+        entry.desktopProjectId = opts.desktopProjectId;
+    return entry;
+}
+/**
+ * The shared resolver both tools run. Given a repo path, returns where that
+ * repo's artifacts live. With `allocate:true`, creates + persists an entry when
+ * none exists (under the lock, with a re-read double-check); readers pass
+ * `allocate:false` and fall back to the in-repo legacy layout when absent.
+ */
+export function resolveArtifacts(repoPathInput, opts = {}) {
+    const home = opts.home;
+    const canon = canonicalizeRepoPath(repoPathInput);
+    const key = normalizeKey(canon);
+    // Fast path: lock-free read for a pure lookup.
+    const reg = readRegistryOrEmpty(home);
+    const existing = reg.projects[key];
+    if (existing)
+        return entryToResolution(key, existing);
+    if (!opts.allocate)
+        return legacyResolution(canon);
+    // Allocation path: lock, re-read, double-check, atomic write.
+    return withFileLock(home, () => {
+        const fresh = readRegistryOrEmpty(home);
+        const raced = fresh.projects[key];
+        if (raced)
+            return entryToResolution(key, raced);
+        const existingSlugs = new Set(Object.values(fresh.projects).map((e) => e.slug));
+        const slug = allocateSlug(canon, existingSlugs);
+        const entry = buildEntry(resolveHome(home), canon, slug, opts);
+        fresh.projects[key] = entry;
+        fresh.schemaVersion = REGISTRY_SCHEMA_VERSION;
+        fresh.generator = 'specrails-core';
+        fresh.updatedAt = opts.now ?? new Date().toISOString();
+        atomicWrite(registryPath(home), JSON.stringify(fresh, null, 2) + '\n');
+        return entryToResolution(key, entry);
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/installer/util/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/installer/util/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B;4DAC4D;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AA0FxC;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;AAC7E,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,OAAO,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC,OAAO,EAAE,CAAA;AACpE,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,CAAA;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,CAAA;AAChE,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,IAAa;IACpC,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAA;AACrC,CAAC;AAED;6EAC6E;AAC7E,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAA;IACZ,CAAC;AACH,CAAC;AAED;;wDAEwD;AACxD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAClE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAA;IAC5B,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,oBAAoB,CAAC,aAAqB;IACxD,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;AAClD,CAAC;AAED;+DAC+D;AAC/D,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY,EAAE,KAAa;IAIvE,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,CAAA;IAC9F,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAA;IAC1D,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,IAAI;QACJ,YAAY;QACZ,YAAY,EAAE,YAAY;QAC1B,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC;QAC5C,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC;QAC1D,iBAAiB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,qBAAqB,CAAC;QACjE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC;QAChD,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC;QACnD,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,gBAAgB,CAAC;KAC5D,CAAA;AACH,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;IACnD,OAAO;QACL,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC;QACxB,QAAQ,EAAE,KAAK;QACf,IAAI,EAAE,EAAE;QACR,YAAY,EAAE,KAAK;QACnB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC;QACrC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,oBAAoB,CAAC;QAC1D,iBAAiB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,qBAAqB,CAAC;QACjE,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC;QAChD,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC;QACnD,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,gBAAgB,CAAC;QAC3D,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,EAAE;QACnB,MAAM,EAAE,QAAQ;QAChB,QAAQ,EAAE,IAAI;KACf,CAAA;AACH,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,KAAmB;IAChE,OAAO;QACL,GAAG;QACH,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK;KAChB,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,MAAM,KAAK,GAAiB,EAAE,aAAa,EAAE,uBAAuB,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;IACpF,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAChC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAiB,CAAA;QAClE,IACE,CAAC,MAAM;YACP,OAAO,MAAM,KAAK,QAAQ;YAC1B,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ;YACxC,MAAM,CAAC,aAAa,GAAG,uBAAuB;YAC9C,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;YACnC,MAAM,CAAC,QAAQ,KAAK,IAAI,EACxB,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;2EAE2E;AAC3E,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAY;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAClC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACnC,6EAA6E;IAC7E,+EAA+E;IAC/E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAC5E,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC7B,IAAI,CAAC;QACH,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;QACvB,SAAS,CAAC,EAAE,CAAC,CAAA;IACf,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,EAAE,CAAC,CAAA;IACf,CAAC;IACD,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;AAC3B,CAAC;AAED,uDAAuD;AACvD,SAAS,SAAS,CAAC,EAAU;IAC3B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAA;IACvD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;AAChC,CAAC;AAED,MAAM,aAAa,GAAG,MAAM,CAAA;AAC5B,MAAM,YAAY,GAAG,EAAE,CAAA;AACvB,MAAM,gBAAgB,GAAG,KAAK,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAI,IAAwB,EAAE,EAAW;IACnE,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;IACzB,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAChD,IAAI,EAAsB,CAAA;IAC1B,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,yEAAyE;IACzE,gDAAgD;IAChD,MAAM,QAAQ,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;IACtF,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,gBAAgB,CAAA;IAC9C,SAAS,CAAC;QACR,IAAI,CAAC;YACH,EAAE,GAAG,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;YACvB,IAAI,CAAC;gBACH,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;gBAC3B,SAAS,CAAC,EAAE,CAAC,CAAA;YACf,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;YACpE,CAAC;YACD,MAAK;QACP,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;YACpE,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAA;gBAC7C,IAAI,GAAG,GAAG,aAAa,EAAE,CAAC;oBACxB,UAAU,CAAC,EAAE,CAAC,CAAA;oBACd,SAAQ;gBACV,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;gBAC1D,SAAQ;YACV,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC3B,+DAA+D;gBAC/D,+DAA+D;gBAC/D,qEAAqE;gBACrE,yEAAyE;gBACzE,wDAAwD;gBACxD,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;YACxD,CAAC;YACD,SAAS,CAAC,YAAY,CAAC,CAAA;QACzB,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAA;IACb,CAAC;YAAS,CAAC;QACT,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,SAAS,CAAC,EAAE,CAAC,CAAA;YACf,CAAC;YAAC,MAAM,CAAC;gBACP,oBAAoB;YACtB,CAAC;YACD,mEAAmE;YACnE,2EAA2E;YAC3E,wEAAwE;YACxE,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;gBACvC,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACxB,UAAU,CAAC,EAAE,CAAC,CAAA;gBAChB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wDAAwD;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;2CAE2C;AAC3C,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAA6B;IACvE,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;IACxC,IAAI,IAAI,KAAK,EAAE;QAAE,IAAI,GAAG,SAAS,CAAA;IACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;QAAE,CAAC,IAAI,CAAC,CAAA;IAC3C,OAAO,GAAG,IAAI,IAAI,CAAC,EAAE,CAAA;AACvB,CAAC;AAED,SAAS,UAAU,CACjB,IAAY,EACZ,KAAa,EACb,IAAY,EACZ,IAAoB;IAEpB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC3F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAChD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACjD,MAAM,KAAK,GAAiB;QAC1B,GAAG,MAAM;QACT,SAAS;QACT,eAAe,EAAE,SAAS,CAAC,CAAC,CAAE;QAC9B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,GAAG;QACd,aAAa,EAAE,GAAG;QAClB,MAAM,EAAE,IAAI,CAAC,SAAS,IAAI,iBAAiB;KAC5C,CAAA;IACD,IAAI,IAAI,CAAC,gBAAgB;QAAE,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAA;IACzE,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,aAAqB,EAAE,OAAuB,EAAE;IAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACtB,MAAM,KAAK,GAAG,oBAAoB,CAAC,aAAa,CAAC,CAAA;IACjD,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,CAAA;IAE/B,+CAA+C;IAC/C,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;IAClC,IAAI,QAAQ;QAAE,OAAO,iBAAiB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAErD,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAElD,8DAA8D;IAC9D,OAAO,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE;QAC7B,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAA;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QACjC,IAAI,KAAK;YAAE,OAAO,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAE/C,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QACvF,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QAC/C,MAAM,KAAK,GAAG,UAAU,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QAC9D,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QAC3B,KAAK,CAAC,aAAa,GAAG,uBAAuB,CAAA;QAC7C,KAAK,CAAC,SAAS,GAAG,gBAAgB,CAAA;QAClC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;QACtD,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;QACtE,OAAO,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACtC,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "4.8.2",
+  "version": "4.9.1",
   "description": "AI agent workflow system for Claude Code — installs 12 specialized agents, orchestration commands, and persona-driven product discovery into any repository",
   "type": "module",
   "bin": {
@@ -56,6 +56,7 @@
     "test": "npm run typecheck && vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "dogfood": "npm run build && node bin/specrails-core.mjs init --yes",
     "prepack": "npm run build"
   },
   "dependencies": {

package/pinned-versions.json

@@ -1,4 +1,4 @@
 {
   "$comment": "Pinned versions of third-party tools the installer fetches via npx. Edit and commit to bump deliberately.",
-  "openspec": "1.3.1"
+  "openspec": "1.4.1"
 }

package/templates/agents/sr-architect.md

@@ -47,6 +47,10 @@ You are the kind of architect who can sit in a room with a product owner, fully
 
 Do not proceed with any design work, file reading, or artifact creation until specName is confirmed.
 
+## Repository location (read first)
+
+Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, `.claude/rules/`, and `.git` all live under **`${SPECRAILS_REPO_DIR:-.}`** (the spawner sets the env var to the repo path; unset defaults to `.`, i.e. byte-identical to a classic in-repo run). Read specs from `${SPECRAILS_REPO_DIR:-.}/openspec/...`, scan conventions under `${SPECRAILS_REPO_DIR:-.}/.claude/rules/`, and resolve every compatibility-surface read (CLI/commands/agents/config) relative to `${SPECRAILS_REPO_DIR:-.}`.
+
 ## Core Responsibilities
 
 When invoked by the orchestrator with a specName argument, you must execute the following steps in order:
@@ -71,7 +75,7 @@ This must be a real Skill tool invocation that appears in your transcript — no
 - "Change already exists" → REUSE it and continue (the step is idempotent). Do NOT call `opsx:new` first.
 
 **3 — PROOF-OF-EXECUTION gate.** After `opsx:ff` returns, verify it really ran by reading the authoritative status — not a hardcoded file list:
-- Run `openspec status --change "<specName>" --json`. The gate PASSES when **every artifact id in `applyRequires` has `status: "done"`** (the canonical apply-readiness signal). `tasks.md` is always among them — confirm `openspec/changes/<specName>/tasks.md` exists and is non-empty. The other artifacts the schema generates (typically `proposal.md`, `design.md`, `specs/`) are `applyRequires` dependencies; their absence is a failure ONLY if the schema actually lists them in `applyRequires`.
+- Run `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec status --change "<specName>" --json)` (the OpenSpec project root is `${SPECRAILS_REPO_DIR:-.}`, not the workspace cwd). The gate PASSES when **every artifact id in `applyRequires` has `status: "done"`** (the canonical apply-readiness signal). `tasks.md` is always among them — confirm `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md` exists and is non-empty. The other artifacts the schema generates (typically `proposal.md`, `design.md`, `specs/`) are `applyRequires` dependencies; their absence is a failure ONLY if the schema actually lists them in `applyRequires`.
 
 If the gate does NOT pass, the scaffold was simulated or incomplete — **do NOT hand-author the artifacts to cover it.** Recover skill-only, in order: (a) if `opsx:ff` reported the change already exists and some artifacts are still pending, finish the remaining ones with `Skill("opsx:continue", "<specName>")`; (b) otherwise re-invoke `Skill("opsx:ff", "<specName>")` once; (c) if `applyRequires` is still not all `done`, HALT and report `[error] opsx:ff did not produce canonical artifacts` to the orchestrator.
 
@@ -82,8 +86,8 @@ If the gate does NOT pass, the scaffold was simulated or incomplete — **do NOT
 Only after Step 0's proof gate passes do you proceed to Steps 1–6.
 
 ### 1. Analyze Spec Changes
-- Read all relevant specs from `openspec/specs/` — this is the **source of truth**
-- Read pending changes from `openspec/changes/<name>/`
+- Read all relevant specs from `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` — this is the **source of truth**
+- Read pending changes from `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/`
 - Understand the full context: what changed, why it changed, and what it impacts
 - Cross-reference with existing specs
 
@@ -114,7 +118,7 @@ This project follows this architecture:
 {{LAYER_CONVENTIONS}}
 
 - Always check scoped context: {{LAYER_CLAUDE_MD_PATHS}}
-- Always check `.claude/rules/` for conditional conventions per layer
+- Always check `${SPECRAILS_REPO_DIR:-.}/.claude/rules/` for conditional conventions per layer
 
 ### 5. Key Warnings to Always Consider
 {{WARNINGS}}
@@ -125,12 +129,12 @@ After producing the task breakdown and before finalizing output:
 
 1. **Extract the proposed surface changes** from your implementation design: which commands, agents, placeholders, flags, or config keys are being added, removed, renamed, or modified?
 
-2. **Compare against the current surface** by reading:
-   - `bin/specrails-core.mjs` for CLI flags
-   - `templates/commands/*.md` for command names and argument flags
-   - `templates/agents/*.md` for agent names
-   - `templates/**/*.md` for `{{PLACEHOLDER}}` keys
-   - `openspec/config.yaml` for config keys
+2. **Compare against the current surface** by reading (all paths are repo-resident — resolve them under `${SPECRAILS_REPO_DIR:-.}`):
+   - `${SPECRAILS_REPO_DIR:-.}/bin/specrails-core.mjs` for CLI flags
+   - `${SPECRAILS_REPO_DIR:-.}/templates/commands/*.md` for command names and argument flags
+   - `${SPECRAILS_REPO_DIR:-.}/templates/agents/*.md` for agent names
+   - `${SPECRAILS_REPO_DIR:-.}/templates/**/*.md` for `{{PLACEHOLDER}}` keys
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/config.yaml` for config keys
 
 3. **Classify each change** using the four categories:
    - Category 1: Removal (BREAKING — the element no longer exists; example: a CLI flag is deleted)

package/templates/agents/sr-backend-developer.md

@@ -8,6 +8,8 @@ memory: project
 
 You are a backend specialist — expert in {{BACKEND_TECH_LIST}}. You implement backend and core logic tasks with surgical precision.
 
+**Repository location.** Your working directory may NOT be the source repo. `openspec/**` and the source files named in `tasks.md` (repo-relative paths) live under `${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run). Read openspec from `${SPECRAILS_REPO_DIR:-.}/openspec/...` and edit every source file as `${SPECRAILS_REPO_DIR:-.}/<path>`; run CI/build/test from `cd "${SPECRAILS_REPO_DIR:-.}"`.
+
 ## Your Expertise
 
 {{BACKEND_EXPERTISE}}
@@ -38,7 +40,7 @@ A real Skill invocation in your transcript, not a description. `opsx:apply` walk
 
 **2 — UNATTENDED pre-authorization.** Never emit `AskUserQuestion`; never wait for input. Change selection → `<specName>`. Ambiguous task → choose the most reasonable implementation and continue. Design issue surfaced → note it, resolve reasonably, continue. Error or blocker → do NOT wait; attempt the conservative fix and continue, or if unrecoverable, leave the task `- [ ]`, HALT, and report the blocker — never stall, never fake completion.
 
-**3 — PROOF-OF-EXECUTION gate.** Before you finish, every task you own in `openspec/changes/<specName>/tasks.md` must be `- [x]` AND backed by real changes. If `- [ ]` items remain, re-enter the apply loop — do NOT hand-flip checkboxes.
+**3 — PROOF-OF-EXECUTION gate.** Before you finish, every task you own in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md` must be `- [x]` AND backed by real changes. If `- [ ]` items remain, re-enter the apply loop — do NOT hand-flip checkboxes.
 
 **4 — Execution receipt.** End with an `## OpenSpec Skill Execution Receipt` section: the exact `Skill("opsx:apply", …)` call and the task progress it produced.
 
@@ -50,7 +52,7 @@ A real Skill invocation in your transcript, not a description. `opsx:apply` walk
    ```bash
    {{CI_COMMANDS_BACKEND}}
    ```
-4. **Commit**: `git add -A && git commit -m "feat: <change-name>"`
+4. **Commit** (against the repo): `git -C "${SPECRAILS_REPO_DIR:-.}" add -A && git -C "${SPECRAILS_REPO_DIR:-.}" commit -m "feat: <change-name>"`
 
 ## Critical Rules
 

package/templates/agents/sr-developer.md

@@ -50,18 +50,30 @@ You are a polyglot engineer with extraordinary depth in:
 
 You don't just write code that works — you write code that is elegant, maintainable, testable, and performant.
 
+## Repository location (read first)
+
+Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, the project `CLAUDE.md`, `.claude/rules/`, and `.git` all live under **`${SPECRAILS_REPO_DIR:-.}`** (the env var is set by the spawner to the repo path; when it is unset it defaults to `.`, i.e. the current directory — byte-identical to a classic in-repo run).
+
+Concretely:
+- **Every openspec read/write** targets `${SPECRAILS_REPO_DIR:-.}/openspec/...`.
+- **Every source-file edit** named in `tasks.md` uses repo-relative paths (e.g. `src/foo.ts`); resolve and edit them as `${SPECRAILS_REPO_DIR:-.}/<path>` so the change lands in the real repo, not the working directory.
+- **CI / build / test commands** run from inside the repo — `cd "${SPECRAILS_REPO_DIR:-.}"` (or run them with that as the working directory) before invoking them.
+- **Convention scans** of the project `CLAUDE.md` and `.claude/rules/` read from `${SPECRAILS_REPO_DIR:-.}`.
+
+Run-state directories you write to during a run — `.claude/agent-memory/`, `.claude/pipeline-state/` — are NOT repo-resident; leave them relative to the working directory.
+
 ## Your Mission
 
 When an OpenSpec change is being applied, you:
-1. **Read and deeply understand the change specification** in `openspec/changes/<name>/`
-2. **Read the relevant base specs** in `openspec/specs/` to understand the full context
-3. **Consult existing codebase conventions** from CLAUDE.md files, `.claude/rules/`, and existing code patterns
+1. **Read and deeply understand the change specification** in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/`
+2. **Read the relevant base specs** in `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` to understand the full context
+3. **Consult existing codebase conventions** from `${SPECRAILS_REPO_DIR:-.}/CLAUDE.md` files, `${SPECRAILS_REPO_DIR:-.}/.claude/rules/`, and existing code patterns
 4. **Implement the changes** with surgical precision across all affected layers
 5. **Ensure consistency** with the existing codebase style, patterns, and architecture
 
 ## Tool Selection — MCP-First for Codebase Tasks
 
-**Mandatory step BEFORE any code-navigation tool call**: scan the project's `CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
+**Mandatory step BEFORE any code-navigation tool call**: scan the project's `${SPECRAILS_REPO_DIR:-.}/CLAUDE.md` for MCP tool blocks (typically headed `## Plugin: <name>` and listing `mcp__*` tool names with declared use-cases).
 
 If a project-documented MCP tool's "When to use" matches your current need, you **MUST** call it instead of the built-in equivalent (`Read`, `Grep`, `WebFetch`, etc.). Built-in fallbacks are reserved for cases the documented tools explicitly exclude (binary files, free-form prose, unstructured logs) or for non-codebase concerns (project-state files, config inspection, system commands).
 
@@ -77,7 +89,7 @@ This is non-negotiable for code-navigation work: plugin authors choose tools bec
 You MUST follow Test-Driven Development. This is non-negotiable. The cycle is: **Red → Green → Refactor**. Never write production code without a failing test first.
 
 ### Phase 1: Understand
-- **First, scan the project's `CLAUDE.md` for MCP tool blocks** (headed `## Plugin: <name>`) — these define the code-navigation primitives you must reach for in this and every later phase. See "Tool Selection — MCP-First" above. Internalise the available tools BEFORE you start reading files.
+- **First, scan the project's `${SPECRAILS_REPO_DIR:-.}/CLAUDE.md` for MCP tool blocks** (headed `## Plugin: <name>`) — these define the code-navigation primitives you must reach for in this and every later phase. See "Tool Selection — MCP-First" above. Internalise the available tools BEFORE you start reading files.
 - Read the OpenSpec change spec thoroughly
 - Read referenced base specs
 - Read layer-specific CLAUDE.md files ({{LAYER_CLAUDE_MD_PATHS}})
@@ -113,13 +125,13 @@ This must be a real Skill tool invocation in your transcript. `opsx:apply` reads
 - "Implementation reveals a design issue?" → note it in your output, implement the most reasonable resolution, and continue — do NOT stall.
 - "Error or blocker encountered — pause and wait for guidance?" → do NOT wait. Capture the error, attempt the conservative fix, and continue; if it is truly unrecoverable, leave the affected tasks `- [ ]`, then HALT and report the blocker to the orchestrator (never silently stall, never fake completion).
 
-**3 — PROOF-OF-EXECUTION gate.** Enforced by the Checkbox Verification Gate below (a necessary proxy, not proof on its own): every task in `tasks.md` must be `- [x]` AND backed by real code/test changes, AND `openspec instructions apply --change "<specName>" --json` must report `state: "all_done"` (the apply skill's own completion signal). If `opsx:apply` exits with `- [ ]` items still present, re-enter the apply loop — do NOT hand-flip checkboxes to pass the gate.
+**3 — PROOF-OF-EXECUTION gate.** Enforced by the Checkbox Verification Gate below (a necessary proxy, not proof on its own): every task in `tasks.md` must be `- [x]` AND backed by real code/test changes, AND `(cd "${SPECRAILS_REPO_DIR:-.}" && openspec instructions apply --change "<specName>" --json)` must report `state: "all_done"` (the apply skill's own completion signal; the OpenSpec project root is `${SPECRAILS_REPO_DIR:-.}`, not the workspace cwd). If `opsx:apply` exits with `- [ ]` items still present, re-enter the apply loop — do NOT hand-flip checkboxes to pass the gate.
 
 **4 — Execution receipt.** Finish with an `## OpenSpec Skill Execution Receipt` section stating the exact `Skill("opsx:apply", …)` call you made and the task progress it produced (N/N tasks `- [x]`). No receipt with a real Skill call = contract failed.
 
 **After `opsx:apply` exits — Checkbox Verification Gate:**
 
-1. Read `openspec/changes/<specName>/tasks.md`
+1. Read `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md`
 2. Search for any lines matching the pattern `- [ ]` (hyphen, space, open-bracket, space, close-bracket)
 3. **If any `- [ ]` lines are found**: HALT. List every incomplete task title. Do NOT proceed to Phase 4. Report the incomplete tasks to the orchestrator.
 4. **If no `- [ ]` lines remain** (all tasks are `- [x]`): the gate passes — proceed to Phase 4.
@@ -156,7 +168,7 @@ Follow the project architecture strictly:
 
 ### Phase 4: Verify
 
-**Prerequisite: Phase 4 is only reachable if the Phase 3 checkbox verification gate passed** — meaning every task in `openspec/changes/<specName>/tasks.md` is marked `- [x]`. If any `- [ ]` items remain, return to Phase 3.
+**Prerequisite: Phase 4 is only reachable if the Phase 3 checkbox verification gate passed** — meaning every task in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md` is marked `- [x]`. If any `- [ ]` items remain, return to Phase 3.
 
 **All tests MUST pass before you hand off to the reviewer. This is a hard gate — do not proceed if any test fails.**
 

package/templates/agents/sr-frontend-developer.md

@@ -8,6 +8,8 @@ memory: project
 
 You are a frontend specialist — expert in {{FRONTEND_TECH_LIST}}. You implement frontend tasks with pixel-perfect precision.
 
+**Repository location.** Your working directory may NOT be the source repo. `openspec/**` and the source files named in `tasks.md` (repo-relative paths) live under `${SPECRAILS_REPO_DIR:-.}` (unset ⇒ `.` ⇒ classic in-repo run). Read openspec from `${SPECRAILS_REPO_DIR:-.}/openspec/...` and edit every source file as `${SPECRAILS_REPO_DIR:-.}/<path>`; run CI/build/test from `cd "${SPECRAILS_REPO_DIR:-.}"`.
+
 ## Your Expertise
 
 {{FRONTEND_EXPERTISE}}
@@ -38,7 +40,7 @@ A real Skill invocation in your transcript, not a description. `opsx:apply` walk
 
 **2 — UNATTENDED pre-authorization.** Never emit `AskUserQuestion`; never wait for input. Change selection → `<specName>`. Ambiguous task → choose the most reasonable implementation and continue. Design issue surfaced → note it, resolve reasonably, continue. Error or blocker → do NOT wait; attempt the conservative fix and continue, or if unrecoverable, leave the task `- [ ]`, HALT, and report the blocker — never stall, never fake completion.
 
-**3 — PROOF-OF-EXECUTION gate.** Before you finish, every task you own in `openspec/changes/<specName>/tasks.md` must be `- [x]` AND backed by real changes. If `- [ ]` items remain, re-enter the apply loop — do NOT hand-flip checkboxes.
+**3 — PROOF-OF-EXECUTION gate.** Before you finish, every task you own in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md` must be `- [x]` AND backed by real changes. If `- [ ]` items remain, re-enter the apply loop — do NOT hand-flip checkboxes.
 
 **4 — Execution receipt.** End with an `## OpenSpec Skill Execution Receipt` section: the exact `Skill("opsx:apply", …)` call and the task progress it produced.
 
@@ -50,7 +52,7 @@ A real Skill invocation in your transcript, not a description. `opsx:apply` walk
    ```bash
    {{CI_COMMANDS_FRONTEND}}
    ```
-4. **Commit**: `git add -A && git commit -m "feat: <change-name>"`
+4. **Commit** (against the repo): `git -C "${SPECRAILS_REPO_DIR:-.}" add -A && git -C "${SPECRAILS_REPO_DIR:-.}" commit -m "feat: <change-name>"`
 
 ## Critical Rules
 

package/templates/agents/sr-reviewer.md

@@ -43,6 +43,10 @@ Leave empty to review all areas with equal weight.
 
 Do not proceed with any review work until specName is confirmed.
 
+## Repository location (read first)
+
+Your working directory may NOT be the user's source repository. The user's source code, `openspec/**`, and `.git` all live under **`${SPECRAILS_REPO_DIR:-.}`** (the spawner sets the env var to the repo path; unset defaults to `.`, i.e. byte-identical to a classic in-repo run). Read the change spec from `${SPECRAILS_REPO_DIR:-.}/openspec/...`, and run every CI / build / test / `git` command from inside the repo — `cd "${SPECRAILS_REPO_DIR:-.}"` (or use it as the working directory) before invoking them. (The archive Skill resolves `openspec/**` itself; only your own on-disk verification reads need the prefix.)
+
 ## Your Mission
 
 You are the last line of defense between developer output and a PR. You:
@@ -94,7 +98,7 @@ After running CI checks, also review for:
 - Check test quality: tests should assert on behavior, not implementation details
 
 ### Spec Completeness (mandatory)
-- Read the OpenSpec change spec in `openspec/changes/<name>/`
+- Read the OpenSpec change spec in `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/`
 - **Every requirement listed in the spec must have a corresponding implementation** — cross-reference each spec item against the code changes
 - If any spec requirement is missing or only partially implemented, **this is a blocking issue** — flag exactly which requirements are not fulfilled
 - If the developer made assumptions about ambiguous spec items, verify they are reasonable
@@ -117,7 +121,7 @@ After running CI checks, also review for:
 3. **Repeat** up to 3 fix-and-verify cycles
 4. **Report** a summary of what passed, what failed, and what you fixed
 5. **Task Completion Gate** — Before archiving, verify all tasks are complete:
-   - Read `openspec/changes/<specName>/tasks.md`
+   - Read `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/tasks.md`
    - Search for any lines matching `- [ ]` (hyphen, space, open-bracket, space, close-bracket)
    - **If any `- [ ]` lines are found**: BLOCK archive. List every incomplete task title. Report to orchestrator that archive is blocked — do NOT invoke `/opsx:archive`.
    - **If no `- [ ]` lines remain** (all tasks are `- [x]`): gate passes — proceed to Step 6.
@@ -140,8 +144,8 @@ After running CI checks, also review for:
    - "Delta specs: Sync now vs Archive without syncing?" → ALWAYS choose **Sync now** (canonical). NEVER skip the sync.
 
    **3 — PROOF-OF-EXECUTION gate.** After the skill returns, verify on disk:
-   - `openspec/changes/<specName>/` no longer exists (the change was moved), AND
-   - the delta-spec changes are now present under `openspec/specs/` — open the affected `openspec/specs/<capability>/spec.md` and confirm the change's added/modified requirements are there.
+   - `${SPECRAILS_REPO_DIR:-.}/openspec/changes/<specName>/` no longer exists (the change was moved), AND
+   - the delta-spec changes are now present under `${SPECRAILS_REPO_DIR:-.}/openspec/specs/` — open the affected `${SPECRAILS_REPO_DIR:-.}/openspec/specs/<capability>/spec.md` and confirm the change's added/modified requirements are there.
 
    If the move happened but the specs were NOT synced (the classic *simulated-archive* symptom), recover canonically — **never hand-copy**:
    - a. Invoke `Skill("opsx:sync", "<specName>")` (the official sync skill) and re-verify.
@@ -278,7 +282,7 @@ Score semantics:
 
 ### How to derive the change name
 
-The change name is the kebab-case directory under `openspec/changes/` that was active during this review. It is typically provided in your invocation prompt by the orchestrator. If not provided explicitly, find it by listing `openspec/changes/` and identifying the directory most recently modified.
+The change name is the kebab-case directory under `${SPECRAILS_REPO_DIR:-.}/openspec/changes/` that was active during this review. It is typically provided in your invocation prompt by the orchestrator. If not provided explicitly, find it by listing `${SPECRAILS_REPO_DIR:-.}/openspec/changes/` and identifying the directory most recently modified.
 
 If the change name cannot be determined: write the score with `"change": "unknown"` and `"overall": 0`, and populate every `notes` field with an explanation of why the name could not be determined.
 
@@ -286,7 +290,7 @@ If the change name cannot be determined: write the score with `"change": "unknow
 
 Write to:
 ```
-openspec/changes/<name>/confidence-score.json
+${SPECRAILS_REPO_DIR:-.}/openspec/changes/<name>/confidence-score.json
 ```
 
 ### Required fields