specrails-core 5.2.3 → 5.4.0

package/dist/installer/phases/scaffold.d.ts

@@ -0,0 +1,211 @@
+import type { Provider } from './provider-detect.js';
+/**
+ * The three baseline agents — the COMPLETE set of agents the installer
+ * ships. The implement pipeline depends on all three. Any additional agent
+ * comes from a user-authored profile (`custom-*`), never the installer.
+ *
+ * Mirrors the `allOf` baseline in schemas/profile.v1.json — update
+ * both files together if this set ever changes.
+ */
+export declare const CORE_AGENTS: Set<string>;
+/**
+ * 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.
+ */
+export declare function translateOpsxSkillCallsForGemini(body: string): string;
+/**
+ * Port shared Claude-authored prose to Kimi's directory-skill contract.
+ *
+ * Kimi's TUI/ACP clients intercept `/skill:*`, but a materialized workflow is
+ * already running inside a Session and must activate nested workflows through
+ * Kimi's built-in `Skill` tool (`{ skill, args }`). Emitting slash text here
+ * would silently become ordinary model text under `kimi -p`. Interactive slash
+ * examples therefore belong only in AGENTS/docs, never generated skill bodies.
+ * This is render-only; canonical Claude/Codex/Gemini templates stay unchanged.
+ */
+export declare function translateClaudeTextForKimi(body: string): string;
+export declare function geminiAgentLimitMetadata(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Phase 2 + Phase 3 of the retired install.sh:
+ *   - Detect prior installation state (.claude/.codex/openspec already present).
+ *   - Create the directory skeleton.
+ *   - Copy templates into `.specrails/setup-templates/` (the internal
+ *     staging dir that placement copies from and `update` diffs against).
+ *   - Ensure `.gitignore` excludes the runtime artefacts.
+ *
+ * Placement (`placeArtefacts`) then copies the staged templates directly into
+ * the user's live `.claude/agents/` and `.claude/commands/specrails/` dirs so
+ * the installer finishes in one pass — no follow-up wizard required.
+ */
+export interface ScaffoldInput {
+    /** Absolute path to the specrails-core package (installed via npx). */
+    scriptDir: string;
+    /**
+     * Absolute path to the relocated artifact root — where every Specrails-managed
+     * artifact (.specrails/.claude/.codex/.gemini/.kimi-code and instruction/settings files)
+     * is written. Under relocate-always this is the `$HOME` workspace, NOT the repo.
+     */
+    artifactRoot: string;
+    /**
+     * Absolute path to the user's repo root — the ONLY thing that stays in-repo is
+     * `openspec/**` (installed by init.ts) and git/worktree ops. Used solely by
+     * `detectExistingSetup`'s openspec probe and the gitignore no-op guard.
+     */
+    codeRoot: string;
+    /** Resolved provider from prereqs. */
+    provider: Provider;
+    /** Derived directory name (`.claude` or `.codex`). */
+    providerDir: string;
+    /** Optional explicit allow-list used by config-driven installs. */
+    selectedAgents?: string[];
+    /**
+     * When false, the static-placement helpers do NOT create the per-workspace
+     * mutable seeds (agent-memory dirs, gemini headless acknowledgments). Used by
+     * `installFramework` so the SHARED framework copy stays purely provider-static
+     * — the project layer is seeded separately by `assembleProjectWorkspace`.
+     * Defaults to true (legacy in-place behaviour for `scaffoldInstallation`).
+     */
+    seedProjectDirs?: boolean;
+    /**
+     * When true, place EVERY agent template (the full superset) regardless of
+     * `selectedAgents`. Used by `installFramework` so
+     * the SHARED framework store is a superset that ANY project's selection can
+     * link from — per-project agent filtering then happens at the workspace LINK
+     * step (`linkAgentFiles`), not at materialization. Defaults to false (legacy
+     * selection-honouring placement for in-place `scaffoldInstallation`).
+     */
+    materializeAllAgents?: boolean;
+}
+export interface ScaffoldResult {
+    existingSetup: boolean;
+    createdDirs: string[];
+    copiedFiles: number;
+}
+/**
+ * Returns true iff any of the provider directories already contains
+ * content. The desktop-app-driven path skips the "merge existing?" prompt and
+ * assumes `--yes`; the CLI dispatcher (bin/specrails-core.cjs) should
+ * have prompted before entering this phase.
+ */
+export declare function detectExistingSetup(input: Pick<ScaffoldInput, 'artifactRoot' | 'codeRoot' | 'providerDir'>): boolean;
+/**
+ * Entry point. Creates directories, copies templates, updates
+ * .gitignore. Returns a summary for logging / tests.
+ */
+export declare function scaffoldInstallation(input: ScaffoldInput): ScaffoldResult;
+export interface InstallFrameworkInput {
+    /** Absolute path to the specrails-core package (templates/ + commands/). */
+    scriptDir: string;
+    /** Root of the versioned framework store, e.g. `<home>/.specrails/framework`. */
+    frameworkDir: string;
+    /** Provider whose static subtree is being materialized. */
+    provider: Provider;
+    /** Derived provider dir (`.claude`/`.codex`/`.gemini`/`.kimi-code`). */
+    providerDir: string;
+    /** Framework version (the `<version>/` segment). */
+    version: string;
+    /** Optional explicit agent allow-list (kept for parity with scaffold). */
+    selectedAgents?: string[];
+}
+export interface InstallFrameworkResult {
+    /** `<frameworkDir>/<version>/<providerDir>` — root of the static subtree. */
+    providerFrameworkDir: string;
+    /** `<frameworkDir>/<version>` — the version root (also holds setup-templates/). */
+    versionDir: string;
+    /** True when a fresh materialization happened; false when the idempotent skip fired. */
+    materialized: boolean;
+}
+/** Path to the per-version, per-provider materialization marker (manifest hash). */
+export declare function frameworkStampPath(versionDir: string, providerDir: string): string;
+/**
+ * Validate one provider in a materialized version without needing the source
+ * package. Used by the final swap gate: the stamp identity and current output
+ * hash must still agree immediately before `current` moves.
+ */
+export declare function frameworkMaterializationProblem(versionDir: string, version: string, provider: Provider, providerDir: string): string | null;
+/**
+ * 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 declare function installFramework(input: InstallFrameworkInput): InstallFrameworkResult;
+/**
+ * Atomically point `<frameworkDir>/current` at `<version>` so every workspace's
+ * provider links resolve through `current/...` and an update is a single swap.
+ */
+export declare function ensureCurrentSymlink(frameworkDir: string, version: string): void;
+export interface AssembleProjectWorkspaceInput {
+    /** The per-project workspace artifact root (= resolveArtifacts artifactRoot). */
+    workspace: string;
+    /** Root of the versioned framework store (the parent of `current/`). */
+    frameworkDir: string;
+    /** Provider whose subtrees are linked into the workspace. */
+    provider: Provider;
+    /** Derived provider dir (`.claude`/`.codex`/`.gemini`/`.kimi-code`). */
+    providerDir: string;
+    /** Framework version (used for the manifest record). */
+    version: string;
+    /** The user's real repo (drives PROJECT_NAME + gemini ack keying). */
+    codeRoot: string;
+    /** specrails-core package dir (for the manifest hash sources). */
+    scriptDir: string;
+    /**
+     * Optional agent allow-list. Drives BOTH which framework agents are LINKED
+     * into the workspace (`linkAgentFiles`) AND which agent-memory dirs are seeded.
+     * Undefined = the CORE trio only (the lean default). The SHARED framework store
+     * is always the full superset; this is where per-project filtering happens.
+     */
+    selectedAgents?: string[];
+    /**
+     * When true, the static provider subtrees (`agents`/`commands`/`skills`/`rules`)
+     * and the settings file are COPIED as real files from the framework store into
+     * the workspace instead of SYMLINKED. Used by the in-repo standalone install
+     * (`init`/`update` with `artifactRoot === codeRoot`) so the repo gets real,
+     * committable files — a symlink into `$HOME/.specrails/framework` would be
+     * invisible to a standalone user's `claude`/`codex`/`gemini`/`kimi` running in the
+     * repo. The PROJECT layer (agent-memory, manifest, instruction files) is real
+     * either way. Defaults to false (relocated workspaces symlink — the desktop /
+     * `--relocate` path).
+     */
+    copyStatics?: boolean;
+}
+export interface AssembleProjectWorkspaceResult {
+    /** Per-linked-subtree mechanism, for diagnostics (copy-fallback loses O(1) swap). */
+    links: Record<string, 'symlink' | 'junction' | 'copy'>;
+    /** Agent ids whose memory dirs were seeded as real writable dirs. */
+    seededMemoryAgents: string[];
+}
+/**
+ * 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 declare function assembleProjectWorkspace(input: AssembleProjectWorkspaceInput): AssembleProjectWorkspaceResult;
+/**
+ * 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 declare function writeGeminiAgentAcknowledgments(repoRoot: string, agentIds: string[], agentsBaseDir?: string): void;

package/dist/installer/phases/scaffold.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { constants, cpSync, mkdtempSync, renameSync, rmSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { atomicSymlinkSwap, copyDir, copyFile, isDir, isSymlink, listDir, mkdirp, pathExists, readBytes, readTextFile, removePath, symlinkOrCopy, writeFileLf, } from '../util/fs.js';
 import { info, ok, warn } from '../util/logger.js';
 import { buildManifest, writeManifestFiles } from './manifest.js';
@@ -152,7 +153,7 @@ const SKILL_FROM_COMMAND = {
     },
     'sr-batch-implement': {
         command: 'batch-implement',
-        description: 'sr:batch-implement — Batch implementation orchestrator. Accepts multiple feature references, computes dependency-aware execution waves, invokes sr:implement per wave.',
+        description: 'sr:batch-implement — Run multiple frozen specs as one programmatic agent workflow.',
     },
     'sr-compat-check': {
         command: 'compat-check',
@@ -322,21 +323,6 @@ export function scaffoldInstallation(input) {
         const skillsSubdir = input.provider === 'gemini' ? 'agents' : 'skills';
         info(`Placed ${skills.placed} ${skillsLabel}(s) into ${input.providerDir}/${skillsSubdir}/`);
     }
-    const pipelineContract = providerPipelineContract(input.scriptDir);
-    if (input.provider === 'codex') {
-        for (const name of ['implement', 'batch-implement', 'retry']) {
-            prependSkillContract(path.join(input.artifactRoot, '.codex', 'skills', name, 'SKILL.md'), pipelineContract);
-        }
-    }
-    else if (input.provider === 'gemini') {
-        for (const name of ['implement', 'batch-implement', 'retry']) {
-            const file = path.join(input.artifactRoot, '.gemini', 'commands', 'specrails', `${name}.toml`);
-            if (pipelineContract && pathExists(file)) {
-                const source = readTextFile(file);
-                writeFileLf(file, source.replace("prompt = '''\n", "prompt = '''\n" + pipelineContract));
-            }
-        }
-    }
     // --- Codex provider settings + AGENTS.md initial content ---
     if (input.provider === 'codex') {
         const written = applyCodexSettings(input);
@@ -1373,17 +1359,15 @@ function writeKimiWorkflowSkill(args) {
         '',
     ].join('\n');
     writeFileLf(args.dest, frontmatter +
-        (pathExists(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md'))
-            ? readTextFile(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md')) + '\n' : '') +
-        KIMI_NESTED_SKILL_CONTRACT +
-        KIMI_ROLE_EXECUTION_CONTRACT +
-        KIMI_RUNTIME_CONTEXT_CONTRACT +
-        rendered);
+        (['implement', 'batch-implement', 'retry'].includes(args.commandName) ? rendered :
+            (pathExists(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md'))
+                ? readTextFile(path.join(path.dirname(args.src), '..', '..', 'runtime', 'provider-pipeline.md')) + '\n' : '') +
+                KIMI_NESTED_SKILL_CONTRACT +
+                KIMI_ROLE_EXECUTION_CONTRACT +
+                KIMI_RUNTIME_CONTEXT_CONTRACT +
+                rendered));
 }
 function adaptKimiWorkflowBody(commandName, body) {
-    if (commandName === 'batch-implement') {
-        return adaptKimiBatchImplement(body);
-    }
     if (commandName === 'auto-propose-backlog-specs') {
         return adaptKimiAutoPropose(body);
     }
@@ -1396,30 +1380,7 @@ function adaptKimiWorkflowBody(commandName, body) {
     if (commandName === 'telemetry') {
         return renderKimiTelemetryWorkflow();
     }
-    if (commandName === 'retry') {
-        return adaptKimiRetry(body);
-    }
-    if (commandName !== 'implement')
-        return body;
-    return body.replace('##### Invocation configuration', [
-        '##### Kimi invocation configuration',
-        '',
-        'Keep the parsed `AGENT_MODEL` map as structured orchestration data.',
-        'Resolve each role model from its exact profile value and put it in the',
-        'role-wave JSON `model` field; absent values use `k3`. Shell variables',
-        'from earlier tools are not persistent. Never rewrite role frontmatter',
-        'or translate a Claude model alias into a Kimi model.',
-        '',
-        'Every implementation role uses `workspace:"current"` and the same',
-        'aggregate execution context. Serialize writers within supplied roots;',
-        'no per-ticket full pipeline, nested worktree, copied-file merge or',
-        'replacement run. The runner preserves shared backlog and frozen specs',
-        'even though each role has a private execution cwd.',
-        '',
-    ].join('\n'));
-}
-function adaptKimiBatchImplement(body) {
-    return body.replace('Delegate to implement once with all frozen specs and selected roots.', 'Activate `Skill(skill="specrails-implement", args="<all original arguments>")` once in this orchestrator with all frozen specs and selected roots. Do not launch a role wave of full implementations or one implementation per ticket.');
+    return body;
 }
 function adaptKimiAutoPropose(body) {
     return body
@@ -1437,21 +1398,6 @@ function adaptKimiAutoPropose(body) {
         .replaceAll('The Explore agent receives this prompt:', 'The sr-product-analyst role receives this prompt:')
         .replaceAll('After the Explore agent completes:', 'After the sr-product-analyst role completes:');
 }
-function adaptKimiRetry(body) {
-    return body + [
-        '',
-        '## Kimi direct-role continuation',
-        '',
-        'Use the existing runtime status and exact absolute context. Invoke only',
-        'the required sr-* or profile role through a foreground role wave, using',
-        '`workspace:"current"`; do not activate a nested specrails-implement.',
-        'Pass the complete bounded handoff explicitly, including every frozen',
-        'criterion, selected roots, current phase and next action. Native session',
-        'memory is not a substitute. Preserve valid completed phases and source',
-        'work when a later reviewer or archive step is blocked.',
-        '',
-    ].join('\n');
-}
 function renderKimiEnrichWorkflow() {
     return [
         '# Enrich SpecRails for Kimi Code',
@@ -1937,6 +1883,8 @@ function renderInitialKimiAgentsMd(repoRoot) {
         '`.kimi-code/specrails/run-skill.mjs`. Role skills live at',
         '`.kimi-code/skills/<sr-*|custom-*>/SKILL.md` and are launched by workflows in',
         'separate helper-managed `kimi -p --output-format stream-json` processes.',
+        'Inside a programmatic runtime role, follow the supplied OpenSpec tools and',
+        'frozen scope instead; never start a nested implementation workflow.',
         '',
         '## Conventions',
         '',
@@ -1956,40 +1904,7 @@ function renderInitialKimiAgentsMd(repoRoot) {
     ].join('\n');
 }
 function renderInitialGeminiMd(repoRoot) {
-    const projectName = path.basename(repoRoot);
-    return [
-        AGENTS_MD_START,
-        '',
-        `# ${projectName} — agent instructions`,
-        '',
-        'This project uses the **specrails** agent workflow under `.gemini/`.',
-        'See `.gemini/commands/specrails/` for the slash commands and `.gemini/agents/`',
-        'for the `sr-*` subagents available to gemini sessions in this repository.',
-        '',
-        '## Conventions',
-        '',
-        '- Read specs from `.specrails/local-tickets.json` when implementing',
-        '  numbered tickets (`#42`, `#71` etc.).',
-        '- Prefer the `/specrails:*` commands (implement, batch-implement, …) over',
-        '  ad-hoc edits when one covers the task.',
-        '- Agent execution is enabled via `.gemini/settings.json`',
-        '  (`experimental.enableAgents: true`).',
-        '',
-        AGENTS_MD_END,
-        '',
-    ].join('\n');
-}
-function providerPipelineContract(scriptDir) {
-    const source = path.join(scriptDir, 'templates', 'runtime', 'provider-pipeline.md');
-    return pathExists(source) ? readTextFile(source) + '\n\n' : '';
-}
-function prependSkillContract(file, contract) {
-    if (!contract || !pathExists(file))
-        return;
-    const source = readTextFile(file);
-    const end = source.startsWith('---\n') ? source.indexOf('\n---\n', 4) : -1;
-    const index = end < 0 ? 0 : end + 5;
-    writeFileLf(file, source.slice(0, index) + '\n' + contract + source.slice(index));
+    return renderInitialAgentsMd(repoRoot).replace(AGENTS_MD_END, 'Read provider rules from `.gemini/`.\n\n' + AGENTS_MD_END);
 }
 function assertPipelineRuntimeSource(scriptDir) {
     const contractFile = path.join(scriptDir, 'integration-contract.json');
@@ -2009,6 +1924,22 @@ function placePipelineRuntime(input) {
     copyFile(source, path.join(dest, 'pipeline-state.mjs'));
     writeFileLf(path.join(dest, 'pipeline.mjs'), "import { runPipelineCli } from './pipeline-state.mjs'\n" +
         "process.exitCode = await runPipelineCli(process.argv.slice(2))\n");
+    const runtime = path.join(input.scriptDir, 'dist', 'agent-runtime', 'cli.js');
+    if (pathExists(runtime)) {
+        writeFileLf(path.join(dest, 'agent-runtime.mjs'), `import { runRuntimeCommand } from ${JSON.stringify(pathToFileURL(runtime).href)}\n` +
+            `import { parseArgs } from ${JSON.stringify(pathToFileURL(path.join(input.scriptDir, 'dist', 'installer', 'cli.js')).href)}\n` +
+            "const { subcommand, flags, positionals } = parseArgs(process.argv.slice(2))\n" +
+            "try { process.exitCode = await runRuntimeCommand(flags, [subcommand, ...positionals].filter(Boolean)) } catch (error) { console.error(error.message); process.exitCode = 1 }\n");
+        const configPath = path.join(input.artifactRoot, '.specrails', 'agent-runtime.json');
+        if (!pathExists(configPath)) {
+            const provider = input.provider;
+            writeFileLf(configPath, JSON.stringify({ schemaVersion: 1, enabled: true,
+                providers: [{ id: provider, kind: 'cli', cli: provider }],
+                agents: Object.fromEntries(['architect', 'developer', 'reviewer'].map(role => [role, { provider, maxTurns: 100 }])), verification: [],
+            }, null, 2) + '\n');
+        }
+        return 3;
+    }
     return 2;
 }
 function pruneLegacyArtifacts(input) {
@@ -2317,19 +2248,18 @@ function renderInitialAgentsMd(repoRoot) {
         '',
         `# ${projectName} — agent instructions`,
         '',
-        'This project uses the **specrails** agent workflow under `.codex/`.',
-        'See `.codex/skills/` for the catalog of agent skills available to codex',
-        'sessions in this repository.',
+        'Implementation is coordinated by the Specrails programmatic agent runtime.',
+        'Use the frozen scope and official OpenSpec workflow supplied for your role.',
+        'Do not start another implement or batch-implement workflow inside a role.',
         '',
-        '## Conventions',
+        '## Repository context',
         '',
-        '- Read specs from `.specrails/local-tickets.json` when implementing',
-        '  numbered tickets (`#42`, `#71` etc.).',
-        '- Prefer the skills in `.codex/skills/sr-*` over ad-hoc edits when a',
-        '  skill covers the task (implement, batch-implement, refactor-recommender,',
-        '  compat-check, why, ...).',
-        '- Honour the sandbox policy declared in `.codex/config.toml`',
-        '  (`sandbox_mode` + `approval_policy` top-level keys).',
+        '- Read project README, CONTRIBUTING and relevant nested instructions.',
+        '- Use package manifests and checked-in build wrappers for actual commands.',
+        '- Read API contracts before changing consumers or generated code.',
+        '- Keep edits within the admitted repositories; report permission blockers',
+        '  with the affected repository and path instead of repeating the attempt.',
+        '- Report incomplete tasks and their concrete reasons in the role result.',
         '',
         AGENTS_MD_END,
         '',