@ai-sdlc/orchestrator 0.5.0 → 0.9.0

package/dist/cli/commands/git-remote.d.ts

@@ -0,0 +1,49 @@
+/**
+ * git remote parsing — extract org/repo from `git remote get-url origin`
+ * to substitute into pipeline.yaml during init.
+ *
+ * Why this exists: AISDLC-78 — fresh installs got a literal `your-org`
+ * placeholder in their pipeline.yaml, which made the file unrunnable
+ * until the user noticed and edited it. We auto-detect the org/repo
+ * from the git remote and only fall back to placeholders when no
+ * remote is configured (e.g. a brand-new local-only repo).
+ */
+export interface RemoteInfo {
+    /** Organization or user name. */
+    org: string;
+    /** Repository name (without `.git` suffix). */
+    repo: string;
+    /** Whether the values came from a real git remote (vs the fallback). */
+    detected: boolean;
+}
+/**
+ * Parse a single remote URL into org/repo. Supports:
+ *  - https://github.com/foo/bar.git
+ *  - https://github.com/foo/bar
+ *  - git@github.com:foo/bar.git
+ *  - ssh://git@github.com/foo/bar.git
+ *  - git@gitlab.example.com:group/subgroup/repo.git (org=group, repo=repo)
+ */
+export declare function parseRemoteUrl(url: string): RemoteInfo | null;
+export interface DetectRemoteOptions {
+    /** Override `execSync` for tests. */
+    execImpl?: (cmd: string, opts: {
+        cwd: string;
+        encoding: 'utf-8';
+        stdio: unknown;
+    }) => string;
+    /** Project directory (defaults to process.cwd). */
+    cwd?: string;
+}
+/**
+ * Detect the GitHub-style org/repo from the project's git origin remote.
+ * Returns FALLBACK with detected=false when no remote is configured or
+ * when the URL cannot be parsed.
+ */
+export declare function detectGitRemote(opts?: DetectRemoteOptions): RemoteInfo;
+/**
+ * Substitute `your-org` (and optionally `your-repo`) placeholders in a
+ * template body with detected values.
+ */
+export declare function applyRemoteToPipelineYaml(template: string, info: RemoteInfo): string;
+//# sourceMappingURL=git-remote.d.ts.map

package/dist/cli/commands/git-remote.js

@@ -0,0 +1,91 @@
+/**
+ * git remote parsing — extract org/repo from `git remote get-url origin`
+ * to substitute into pipeline.yaml during init.
+ *
+ * Why this exists: AISDLC-78 — fresh installs got a literal `your-org`
+ * placeholder in their pipeline.yaml, which made the file unrunnable
+ * until the user noticed and edited it. We auto-detect the org/repo
+ * from the git remote and only fall back to placeholders when no
+ * remote is configured (e.g. a brand-new local-only repo).
+ */
+import { execSync } from 'node:child_process';
+const FALLBACK = { org: 'your-org', repo: 'your-repo', detected: false };
+/**
+ * Parse a single remote URL into org/repo. Supports:
+ *  - https://github.com/foo/bar.git
+ *  - https://github.com/foo/bar
+ *  - git@github.com:foo/bar.git
+ *  - ssh://git@github.com/foo/bar.git
+ *  - git@gitlab.example.com:group/subgroup/repo.git (org=group, repo=repo)
+ */
+export function parseRemoteUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // SSH shorthand: git@host:org/repo.git
+    const sshShort = /^[^@\s]+@[^:\s]+:(.+?)\/([^/\s]+?)(?:\.git)?$/.exec(trimmed);
+    if (sshShort) {
+        return { org: sshShort[1].split('/').slice(-1)[0], repo: sshShort[2], detected: true };
+    }
+    // SSH or HTTPS with a scheme
+    let parsed = null;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        parsed = null;
+    }
+    if (parsed) {
+        const path = parsed.pathname.replace(/^\/+/, '').replace(/\.git$/, '');
+        const segments = path.split('/').filter(Boolean);
+        if (segments.length >= 2) {
+            const repo = segments[segments.length - 1];
+            const org = segments[segments.length - 2];
+            return { org, repo, detected: true };
+        }
+    }
+    return null;
+}
+/**
+ * Detect the GitHub-style org/repo from the project's git origin remote.
+ * Returns FALLBACK with detected=false when no remote is configured or
+ * when the URL cannot be parsed.
+ */
+export function detectGitRemote(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const exec = opts.execImpl ?? defaultExec;
+    let url;
+    try {
+        url = exec('git remote get-url origin', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return FALLBACK;
+    }
+    const parsed = parseRemoteUrl(url);
+    return parsed ?? FALLBACK;
+}
+function defaultExec(cmd, opts) {
+    return execSync(cmd, {
+        cwd: opts.cwd,
+        encoding: opts.encoding,
+        stdio: opts.stdio,
+    });
+}
+/**
+ * Substitute `your-org` (and optionally `your-repo`) placeholders in a
+ * template body with detected values.
+ */
+export function applyRemoteToPipelineYaml(template, info) {
+    // Replace the literal `org: your-org` config line with the detected
+    // org. We deliberately match the exact YAML key shape rather than a
+    // bare token so we don't smear the placeholder if it appears elsewhere.
+    let out = template.replace(/(\borg:\s*)your-org(\b)/g, `$1${info.org}$2`);
+    // If the template ever introduces a repo: placeholder, substitute it too.
+    out = out.replace(/(\brepo:\s*)your-repo(\b)/g, `$1${info.repo}$2`);
+    return out;
+}
+//# sourceMappingURL=git-remote.js.map

package/dist/cli/commands/health.d.ts

@@ -1,5 +1,9 @@
 /**
  * ai-sdlc health — validate config, state store, and adapter connectivity.
+ *
+ * AISDLC-78: surfaces the deferred-state-store wording (handled by the
+ * table formatter) and adds an opt-in `--init-state` flag for users who
+ * want the SQLite database created eagerly rather than on first run.
  */
 import { Command } from 'commander';
 export declare const healthCommand: Command;

package/dist/cli/commands/health.js

@@ -1,18 +1,30 @@
 /**
  * ai-sdlc health — validate config, state store, and adapter connectivity.
+ *
+ * AISDLC-78: surfaces the deferred-state-store wording (handled by the
+ * table formatter) and adds an opt-in `--init-state` flag for users who
+ * want the SQLite database created eagerly rather than on first run.
  */
 import { Command } from 'commander';
+import { join } from 'node:path';
 import { Orchestrator } from '../../orchestrator.js';
 import { formatOutput } from '../formatters/index.js';
 export const healthCommand = new Command('health')
     .description('Check orchestrator health')
     .option('--state <path>', 'SQLite state database path')
+    .option('--init-state', 'Eagerly initialize the SQLite state store (defaults to .ai-sdlc/state.db when --state is omitted)')
     .action(async (opts, cmd) => {
     const globalOpts = cmd.parent?.opts() ?? {};
     const format = globalOpts.format ?? 'table';
+    // When the user opts into eager initialization, default the path to
+    // .ai-sdlc/state.db inside the configured config dir so we don't
+    // litter cwd with an unexpected file.
+    const configDir = globalOpts.config ?? '.ai-sdlc';
+    const statePath = opts.state ??
+        (opts.initState ? join(configDir, 'state.db') : undefined);
     const orchestrator = new Orchestrator({
         configDir: globalOpts.config,
-        statePath: opts.state,
+        statePath,
     });
     try {
         const result = await orchestrator.health();

package/dist/cli/commands/init.d.ts

@@ -1,6 +1,32 @@
 /**
  * ai-sdlc init — initialize a project with AI-SDLC config files.
+ *
+ * AISDLC-78 enhancements:
+ *  - Print a 3-line version block at startup so operators see CLI,
+ *    orchestrator, and plugin versions in one place. Drift triggers a
+ *    visible warning instead of silently shipping mismatched binaries.
+ *  - Substitute `your-org` in the pipeline.yaml template using
+ *    `git remote get-url origin` (ssh + https forms supported). Falls
+ *    back to the placeholder only when no remote is configured.
+ *  - Pin `@ai-sdlc/mcp-advisor` in generated `.mcp.json` to the
+ *    orchestrator version that ran init, with an inline opt-out hint.
+ *  - Skip `.cursor/mcp.json` unless Cursor is detected (project-local
+ *    `.cursor/`, user-global `~/.cursor/`) or `--cursor` is passed.
  */
 import { Command } from 'commander';
+/**
+ * Tier-based agent-role templates (AISDLC-79).
+ *
+ * Three named tiers map to escalating tool surfaces. The default (`coding`)
+ * preserves pre-AISDLC-79 behavior plus `NotebookEdit` (parity with the
+ * Claude Code SDK's filesystem editing surface). Higher tiers add tools only
+ * when their use-case justifies the additional surface area / risk.
+ *
+ * See `backlog/decisions/AISDLC-79-agent-role-tools-defaults.md` for rationale.
+ */
+export type AgentRoleTier = 'coding' | 'research' | 'meta';
+export declare const AGENT_ROLE_TIERS: readonly AgentRoleTier[];
+/** Resolve the agent-role.yaml template for a given tier. Default = `coding`. */
+export declare function getAgentRoleYaml(tier?: AgentRoleTier): string;
 export declare const initCommand: Command;
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.js

@@ -1,11 +1,25 @@
 /**
  * ai-sdlc init — initialize a project with AI-SDLC config files.
+ *
+ * AISDLC-78 enhancements:
+ *  - Print a 3-line version block at startup so operators see CLI,
+ *    orchestrator, and plugin versions in one place. Drift triggers a
+ *    visible warning instead of silently shipping mismatched binaries.
+ *  - Substitute `your-org` in the pipeline.yaml template using
+ *    `git remote get-url origin` (ssh + https forms supported). Falls
+ *    back to the placeholder only when no remote is configured.
+ *  - Pin `@ai-sdlc/mcp-advisor` in generated `.mcp.json` to the
+ *    orchestrator version that ran init, with an inline opt-out hint.
+ *  - Skip `.cursor/mcp.json` unless Cursor is detected (project-local
+ *    `.cursor/`, user-global `~/.cursor/`) or `--cursor` is passed.
  */
 import { Command } from 'commander';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } from 'node:fs';
 import { join, basename } from 'node:path';
-import { detectAgents, installMcpServer } from './mcp-setup.js';
+import { detectAgentsDetailed, installMcpServer } from './mcp-setup.js';
 import { detectWorkspace, generateWorkspaceYaml } from './workspace-detect.js';
+import { detectGitRemote, applyRemoteToPipelineYaml } from './git-remote.js';
+import { resolveVersions, formatVersionBlock } from '../versions.js';
 const PIPELINE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
 kind: Pipeline
 metadata:
@@ -35,20 +49,31 @@ spec:
       qualityGates:
         - default-gates
 `;
-const AGENT_ROLE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
+export const AGENT_ROLE_TIERS = ['coding', 'research', 'meta'];
+const AGENT_ROLE_YAML_CODING = `apiVersion: ai-sdlc.io/v1alpha1
 kind: AgentRole
 metadata:
   name: default-agent
 spec:
   role: developer
   goal: Implement issue requirements with tests
+  # Tier: coding-agent (default).
+  # Filesystem + shell editing surface only. No web access, no sub-agent
+  # spawning, no Skill loading. This matches the pre-AISDLC-79 default
+  # plus NotebookEdit (parity with the Claude Code SDK's editing surface).
   tools:
-    - Edit
-    - Write
-    - Read
-    - Glob
-    - Grep
-    - Bash
+    - Edit          # write to existing files
+    - Write         # create new files
+    - Read          # read source / configs
+    - Glob          # discover files by pattern
+    - Grep          # search code
+    - Bash          # run tests, lint, build, git
+    - NotebookEdit  # edit Jupyter notebooks (parity with SDK editing surface)
+    # Excluded by default (opt in via --role research|meta during init):
+    #   - WebFetch    — pulls untrusted remote content into context (research tier)
+    #   - WebSearch   — same (research tier)
+    #   - Task        — spawns sub-agents; cost + reasoning amplification (meta tier)
+    #   - Skill       — loads external skill packs (meta tier)
   constraints:
     maxFilesPerChange: 15
     requireTests: true
@@ -56,6 +81,75 @@ spec:
       - .github/workflows/**
       - .ai-sdlc/**
 `;
+const AGENT_ROLE_YAML_RESEARCH = `apiVersion: ai-sdlc.io/v1alpha1
+kind: AgentRole
+metadata:
+  name: default-agent
+spec:
+  role: research-developer
+  goal: Investigate, gather references, and implement issue requirements with tests
+  # Tier: research-agent.
+  # Coding-tier surface plus read-only web access. Use for tasks that need
+  # to consult external docs, package registries, or RFCs.
+  tools:
+    - Edit          # write to existing files
+    - Write         # create new files
+    - Read          # read source / configs
+    - Glob          # discover files by pattern
+    - Grep          # search code
+    - Bash          # run tests, lint, build, git
+    - NotebookEdit  # edit Jupyter notebooks
+    - WebFetch      # fetch a known URL (docs, RFCs, API references)
+    - WebSearch     # discover sources by query
+    # Excluded (use --role meta to opt in):
+    #   - Task        — spawns sub-agents (meta tier)
+    #   - Skill       — loads external skill packs (meta tier)
+  constraints:
+    maxFilesPerChange: 15
+    requireTests: true
+    blockedPaths:
+      - .github/workflows/**
+      - .ai-sdlc/**
+`;
+const AGENT_ROLE_YAML_META = `apiVersion: ai-sdlc.io/v1alpha1
+kind: AgentRole
+metadata:
+  name: default-agent
+spec:
+  role: meta-developer
+  goal: Orchestrate sub-agents, load skill packs, and implement complex multi-step work
+  # Tier: meta-agent.
+  # Full surface: filesystem + shell + web + sub-agent + skill loading.
+  # Use only when the task legitimately needs sub-agent fan-out or external
+  # skill packs. Higher cost amplification and broader attack surface.
+  tools:
+    - Edit          # write to existing files
+    - Write         # create new files
+    - Read          # read source / configs
+    - Glob          # discover files by pattern
+    - Grep          # search code
+    - Bash          # run tests, lint, build, git
+    - NotebookEdit  # edit Jupyter notebooks
+    - WebFetch      # fetch a known URL
+    - WebSearch     # discover sources by query
+    - Task          # spawn sub-agents for parallel / specialized work
+    - Skill         # load external skill packs (declared capabilities)
+  constraints:
+    maxFilesPerChange: 15
+    requireTests: true
+    blockedPaths:
+      - .github/workflows/**
+      - .ai-sdlc/**
+`;
+const AGENT_ROLE_YAML_BY_TIER = {
+    coding: AGENT_ROLE_YAML_CODING,
+    research: AGENT_ROLE_YAML_RESEARCH,
+    meta: AGENT_ROLE_YAML_META,
+};
+/** Resolve the agent-role.yaml template for a given tier. Default = `coding`. */
+export function getAgentRoleYaml(tier = 'coding') {
+    return AGENT_ROLE_YAML_BY_TIER[tier];
+}
 const QUALITY_GATE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
 kind: QualityGate
 metadata:
@@ -139,24 +233,26 @@ const GITIGNORE_PATHS = ['.ai-sdlc/state.db', '.ai-sdlc/state/', '.ai-sdlc/audit
 function ensureGitignore(projectDir, dryRun, prefix = '') {
     const gitignorePath = join(projectDir, '.gitignore');
     const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
-    // Only check path entries (not comments) to avoid duplicate blocks
-    const missing = GITIGNORE_PATHS.filter((entry) => !existing.includes(entry));
+    const SENTINEL = '# ai-sdlc:runtime-gitignore';
+    if (existing.includes(SENTINEL))
+        return;
+    const missing = GITIGNORE_PATHS.filter((entry) => !existing.split('\n').some((line) => line.trim() === entry));
     if (missing.length === 0)
         return;
     if (dryRun) {
         console.log(`${prefix}  Would update .gitignore`);
         return;
     }
-    const block = '\n# AI-SDLC runtime artifacts\n' + missing.join('\n') + '\n';
+    const block = (existing.length > 0 ? '\n' : '') + `${SENTINEL}\n` + missing.join('\n') + '\n';
     appendFileSync(gitignorePath, block, 'utf-8');
     console.log(`${prefix}  updated .gitignore`);
 }
 /** Initialize a single project directory with AI-SDLC config files. */
-function initProject(projectDir, configDirName, dryRun, prefix = '') {
+function initProject(projectDir, configDirName, dryRun, prefix = '', options = { pipelineYaml: PIPELINE_YAML, tier: 'coding' }) {
     const configDir = join(projectDir, configDirName);
     const files = [
-        { name: 'pipeline.yaml', content: PIPELINE_YAML },
-        { name: 'agent-role.yaml', content: AGENT_ROLE_YAML },
+        { name: 'pipeline.yaml', content: options.pipelineYaml },
+        { name: 'agent-role.yaml', content: getAgentRoleYaml(options.tier) },
         { name: 'quality-gate.yaml', content: QUALITY_GATE_YAML },
         { name: 'autonomy-policy.yaml', content: AUTONOMY_POLICY_YAML },
     ];
@@ -209,11 +305,35 @@ export const initCommand = new Command('init')
     .description('Initialize AI-SDLC configuration in the current project')
     .option('--dry-run', 'Show what would be created without writing files')
     .option('--skip-mcp', 'Skip MCP server auto-configuration')
+    .option('--cursor', 'Force-install Cursor MCP config even if Cursor is not detected')
     .option('-d, --dir <path>', 'Config directory name', '.ai-sdlc')
+    .option('--role <tier>', `Agent-role tool tier: ${AGENT_ROLE_TIERS.join(' | ')} (default: coding)`, 'coding')
     .action(async (opts) => {
     const projectDir = process.cwd();
     const configDirName = opts.dir ?? '.ai-sdlc';
     const dryRun = !!opts.dryRun;
+    const tierInput = (opts.role ?? 'coding');
+    if (!AGENT_ROLE_TIERS.includes(tierInput)) {
+        console.error(`Error: invalid --role value '${tierInput}'. Expected one of: ${AGENT_ROLE_TIERS.join(', ')}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const tier = tierInput;
+    const cursorOptIn = !!opts.cursor;
+    // ── version provenance (AC #1) ────────────────────────────────────
+    const versions = resolveVersions({ workDir: projectDir });
+    console.log(formatVersionBlock(versions));
+    console.log('');
+    // ── pipeline.yaml org/repo substitution (AC #2) ───────────────────
+    const remote = detectGitRemote({ cwd: projectDir });
+    const pipelineYaml = applyRemoteToPipelineYaml(PIPELINE_YAML, remote);
+    if (remote.detected) {
+        console.log(`Detected git remote: ${remote.org}/${remote.repo}`);
+    }
+    else {
+        console.log(`No git origin remote detected — pipeline.yaml will use the 'your-org' placeholder.`);
+    }
+    console.log('');
     // Detect workspace (multi-repo parent directory)
     const workspace = detectWorkspace(projectDir);
     if (workspace.isWorkspace) {
@@ -227,14 +347,30 @@ export const initCommand = new Command('init')
         // Cascade into each child repo
         for (const repo of workspace.repos) {
             console.log(`\n${repo.name}/`);
-            initProject(repo.absPath, configDirName, dryRun, '  ');
+            // Per-repo remote detection so each child gets its own org/repo.
+            const childRemote = detectGitRemote({ cwd: repo.absPath });
+            const childPipeline = applyRemoteToPipelineYaml(PIPELINE_YAML, childRemote);
+            if (childRemote.detected) {
+                console.log(`  detected remote: ${childRemote.org}/${childRemote.repo}`);
+            }
+            initProject(repo.absPath, configDirName, dryRun, '  ', {
+                pipelineYaml: childPipeline,
+                tier,
+            });
         }
         // MCP setup at workspace root (serves all repos)
         if (!opts.skipMcp) {
-            const agents = detectAgents(projectDir, { isWorkspace: true });
+            const { detected, skipped } = detectAgentsDetailed(projectDir, {
+                isWorkspace: true,
+                pinVersion: versions.orchestrator,
+                cursorOptIn,
+            });
             console.log(`\nMCP server setup (workspace root):`);
-            console.log(`  detected ${agents.map((a) => a.name).join(', ')}`);
-            for (const agent of agents) {
+            console.log(`  detected ${detected.map((a) => a.name).join(', ') || '(none)'}`);
+            for (const sk of skipped) {
+                console.log(`  skip ${sk.name} — ${sk.reason}`);
+            }
+            for (const agent of detected) {
                 const status = installMcpServer(projectDir, agent, dryRun);
                 const pad = status === 'merged' ? ' ' : '';
                 console.log(`  ${status}${pad} ${agent.configPath} (${agent.name})`);
@@ -245,12 +381,18 @@ export const initCommand = new Command('init')
     }
     else {
         // Single-repo mode (original behavior)
-        initProject(projectDir, configDirName, dryRun);
+        initProject(projectDir, configDirName, dryRun, '', { pipelineYaml, tier });
         if (!opts.skipMcp) {
-            const agents = detectAgents(projectDir);
+            const { detected, skipped } = detectAgentsDetailed(projectDir, {
+                pinVersion: versions.orchestrator,
+                cursorOptIn,
+            });
             console.log(`\nMCP server setup:`);
-            console.log(`  detected ${agents.map((a) => a.name).join(', ')}`);
-            for (const agent of agents) {
+            console.log(`  detected ${detected.map((a) => a.name).join(', ') || '(none)'}`);
+            for (const sk of skipped) {
+                console.log(`  skip ${sk.name} — ${sk.reason}`);
+            }
+            for (const agent of detected) {
                 const status = installMcpServer(projectDir, agent, dryRun);
                 const pad = status === 'merged' ? ' ' : '';
                 console.log(`  ${status}${pad} ${agent.configPath} (${agent.name})`);

package/dist/cli/commands/mcp-setup.d.ts

@@ -1,5 +1,17 @@
 /**
  * MCP server setup — detect coding agents and install MCP config.
+ *
+ * AISDLC-78 changes:
+ *  - The `npx -y` arg list now pins `@ai-sdlc/mcp-advisor@<version>` so
+ *    fresh installs don't silently jump to whatever is published when
+ *    the orchestrator binary itself was last updated. Each generated
+ *    config file carries a single top-level `_aiSdlcComment` documenting
+ *    how to opt back into floating-tag behaviour.
+ *  - Cursor is no longer detected by binary-on-PATH alone; the user
+ *    must either have a `.cursor/` directory present (real signal of
+ *    use) or pass `--cursor` to opt in. This avoids writing
+ *    `.cursor/mcp.json` into projects whose author has Cursor
+ *    installed but is not using it on this repo.
  */
 export interface DetectedAgent {
     name: string;
@@ -10,7 +22,26 @@ export interface DetectedAgent {
 export interface DetectAgentsOptions {
     /** When true, adds AI_SDLC_WORKSPACE env to server entries. */
     isWorkspace?: boolean;
+    /** Pin the mcp-advisor to this version in generated configs. */
+    pinVersion?: string;
+    /** User explicitly asked for Cursor MCP install. */
+    cursorOptIn?: boolean;
 }
+/**
+ * Returned alongside detected agents to log skip decisions.
+ */
+export interface DetectAgentsResult {
+    detected: DetectedAgent[];
+    /** Per-spec skip explanations for human-readable logging. */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+export declare function detectAgentsDetailed(projectDir: string, options?: DetectAgentsOptions): DetectAgentsResult;
+/**
+ * Backwards-compatible wrapper. New code should prefer detectAgentsDetailed.
+ */
 export declare function detectAgents(projectDir: string, options?: DetectAgentsOptions): DetectedAgent[];
 export declare function installMcpServer(projectDir: string, agent: DetectedAgent, dryRun: boolean): 'created' | 'merged' | 'skipped';
 //# sourceMappingURL=mcp-setup.d.ts.map