@ai-sdlc/orchestrator 0.6.0 → 0.10.0

package/dist/cli/commands/init.js

@@ -1,12 +1,41 @@
 /**
  * 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.
+ *
+ * AISDLC-143 enhancements (Q4(b) of the quality-gate redesign):
+ *  - Default invocation is now an interactive WIZARD (DoR / attestation /
+ *    classifier / branch-protection prompts) so adopters get a guided
+ *    bootstrap instead of having to read the docs to discover features.
+ *  - `--yes` short-circuits all prompts to "accept defaults" (CI/scripts).
+ *  - `--with-X` flags opt into individual features without prompting.
+ *  - `--add <feature>` extends an already-initialized repo with a single
+ *    feature, idempotently — re-running on an initialized repo is safe.
+ *  - `.github/workflows/ai-sdlc-gate.yml` is scaffolded UNCONDITIONALLY
+ *    so every adopter gets the `ai-sdlc/pr-ready` rollup check on day one
+ *    (Q1: prescriptive default).
+ *  - A "next steps" summary closes the run with operator action items
+ *    conditional on which features were chosen.
  */
 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';
-const PIPELINE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
+import { detectGitRemote, applyRemoteToPipelineYaml } from './git-remote.js';
+import { resolveVersions, formatVersionBlock } from '../versions.js';
+import { applyFeatureSelection, buildProductionAdapters, ensureClaudeMdPointer, renderNextSteps, resolveFeatureSelection, } from './init-features.js';
+export const PIPELINE_YAML = `apiVersion: ai-sdlc.io/v1alpha1
 kind: Pipeline
 metadata:
   name: default
@@ -34,21 +63,49 @@ spec:
     - name: review
       qualityGates:
         - default-gates
+  # backlog: holds settings specific to the backlog-task (/ai-sdlc execute)
+  # workflow. These were formerly in a separate pipeline-backlog.yaml file
+  # (deprecated by AISDLC-245.5). Slash commands + pipeline-cli readers
+  # prefer this canonical location.
+  backlog:
+    branching:
+      pattern: 'ai-sdlc/{issueIdLower}-{slug}'
+      targetBranch: main
+      cleanup: on-merge
+    pullRequest:
+      titleTemplate: 'feat: {issueTitle} ({issueId})'
+      descriptionSections:
+        - summary
+        - changes
+        - closes
+      includeProvenance: true
+      closeKeyword: References
 `;
-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 +113,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 +265,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 },
     ];
@@ -205,15 +333,120 @@ function initWorkspaceRoot(workspacePath, repos, configDirName, dryRun) {
         console.log(`  created workspace.yaml`);
     }
 }
+/**
+ * Build the WizardFlags struct from Commander's parsed options. Pulled
+ * out into a function so tests can drive the wizard pipeline directly
+ * without going through Commander's stateful option store.
+ */
+export function buildWizardFlags(opts) {
+    const addRaw = typeof opts.add === 'string' ? opts.add : undefined;
+    let add;
+    if (addRaw === 'dor' ||
+        addRaw === 'attestation' ||
+        addRaw === 'classifier' ||
+        addRaw === 'branch-protection') {
+        add = addRaw;
+    }
+    return {
+        yes: !!opts.yes,
+        withDor: !!opts.withDor,
+        withAttestation: !!opts.withAttestation,
+        withClassifier: !!opts.withClassifier,
+        withBranchProtection: !!opts.withBranchProtection,
+        add,
+        dryRun: !!opts.dryRun,
+    };
+}
+/** Validate a `--add` arg and return either the normalized value or null+error. */
+function validateAddArg(addRaw) {
+    if (addRaw === undefined || addRaw === null || addRaw === false)
+        return { ok: true };
+    if (typeof addRaw !== 'string')
+        return { ok: false, error: `--add must be a string` };
+    const allowed = ['dor', 'attestation', 'classifier', 'branch-protection'];
+    if (!allowed.includes(addRaw)) {
+        return {
+            ok: false,
+            error: `--add: unknown feature '${addRaw}'. Expected one of: ${allowed.join(', ')}.`,
+        };
+    }
+    return { ok: true, value: addRaw };
+}
 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')
+    // ── AISDLC-143 wizard flags ─────────────────────────────────────────
+    .option('-y, --yes', 'Accept all defaults (non-interactive; CI/scripts)')
+    .option('--with-dor', 'Scaffold Definition-of-Ready gate config + workflow')
+    .option('--with-attestation', 'Scaffold attestation infrastructure (audit-only)')
+    .option('--with-classifier', 'Scaffold review classifier config stub')
+    .option('--with-branch-protection', 'Apply recommended branch-protection rule to main (requires gh)')
+    .option('--add <feature>', 'Extend an already-initialized repo with a single feature: dor | attestation | classifier | branch-protection')
     .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;
+    // ── Validate --add early so we error before doing any work. ────────
+    const addCheck = validateAddArg(opts.add);
+    if (!addCheck.ok) {
+        console.error(`Error: ${addCheck.error}`);
+        process.exitCode = 1;
+        return;
+    }
+    const flags = buildWizardFlags(opts);
+    // ── --add path: extend an already-initialized repo ────────────────
+    // AC #7: skip the "always-scaffold-baseline" path entirely; the
+    // wizard dispatcher's `--add` branch knows to write only the chosen
+    // feature's templates (no pipeline.yaml, no MCP setup, no workspace
+    // detection). This is the safe re-run path on a repo that already
+    // ran `ai-sdlc init` once.
+    if (flags.add) {
+        const adapters = buildProductionAdapters();
+        const selection = await resolveFeatureSelection(flags, adapters);
+        console.log(`Extending AI-SDLC config with --add ${flags.add}:`);
+        console.log('');
+        const result = await applyFeatureSelection(projectDir, selection, flags, adapters);
+        renderNextSteps(selection, result, adapters);
+        // Reviewer feedback (round 2, suggestion #5): when the operator
+        // explicitly requested branch-protection via a non-interactive flag
+        // (--add branch-protection here; --yes / --with-branch-protection
+        // in runWizardStage) and the apply failed (gh missing, not
+        // authenticated, etc.), surface a non-zero exit so CI scripts can
+        // detect failure instead of seeing the silent log line.
+        if (flags.add === 'branch-protection' &&
+            result.branchProtection &&
+            !result.branchProtection.applied &&
+            result.branchProtection.error) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // ── 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,37 +460,103 @@ 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})`);
             }
         }
         console.log(`\nAI-SDLC workspace initialized in ${projectDir}/`);
+        // ── AISDLC-143 wizard (workspace root) ────────────────────────
+        // The wizard runs ONCE at the workspace root: the baseline gate
+        // workflow + per-feature workflows live at `<workspace-root>/.github/`,
+        // not in each child repo. Children share the same CI from the
+        // root since GHA workflows always live at the repo root anyway.
+        await runWizardStage(projectDir, flags);
         console.log(`Run 'ai-sdlc health' to verify your configuration.`);
     }
     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})`);
             }
         }
         console.log(`\nAI-SDLC config initialized in ${join(projectDir, configDirName)}/`);
+        // ── AISDLC-143 wizard (single-repo) ──────────────────────────
+        await runWizardStage(projectDir, flags);
         console.log(`Run 'ai-sdlc health' to verify your configuration.`);
     }
 });
+/**
+ * Run the AISDLC-143 wizard stage: prompt the user (or short-circuit on
+ * --yes / --with-X), apply the chosen feature templates, append the
+ * CLAUDE.md pointer, and render the "next steps" summary.
+ *
+ * Pulled out of the inline action body so both the single-repo and
+ * workspace-root branches share the same wiring. Adapters are built
+ * once here (production = real disk writes; tests inject stubs by
+ * calling `applyFeatureSelection`/`renderNextSteps` directly).
+ */
+async function runWizardStage(projectDir, flags) {
+    const adapters = buildProductionAdapters();
+    console.log('');
+    console.log('━━━ Feature wizard ━━━');
+    console.log('');
+    const selection = await resolveFeatureSelection(flags, adapters);
+    console.log('');
+    console.log('Scaffolding selected features:');
+    const result = await applyFeatureSelection(projectDir, selection, flags, adapters);
+    ensureClaudeMdPointer(projectDir, adapters, flags.dryRun);
+    renderNextSteps(selection, result, adapters);
+    // Reviewer feedback (round 2, suggestion #5): when branch-protection
+    // was non-interactively requested (--with-branch-protection or --yes,
+    // both used by CI scripts) and the apply failed (gh missing, not
+    // authenticated, etc.), surface a non-zero exit so CI can detect
+    // failure instead of seeing the silent log line. Interactive prompt
+    // answers don't trip this — the human already saw the error and can
+    // re-run `ai-sdlc init --add branch-protection` themselves.
+    const branchProtectionRequestedNonInteractively = flags.yes || flags.withBranchProtection;
+    if (branchProtectionRequestedNonInteractively &&
+        result.branchProtection &&
+        !result.branchProtection.applied &&
+        result.branchProtection.error) {
+        process.exitCode = 1;
+    }
+}
 //# sourceMappingURL=init.js.map

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

package/dist/cli/commands/mcp-setup.js

@@ -1,23 +1,48 @@
 /**
  * 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.
  */
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
-function standardEntry(env) {
+/**
+ * The opt-out comment we write alongside the pinned mcp-advisor entry.
+ * Lives at the top level of the generated MCP config under a leading-
+ * underscore key so JSON parsers and MCP clients ignore it; humans
+ * editing by hand see exactly how to re-enable floating-latest behaviour.
+ */
+const PIN_OPT_OUT_COMMENT = 'Pinned to the orchestrator version that ran `ai-sdlc init`. ' +
+    'To always pull the latest published mcp-advisor, change args to ["-y", "@ai-sdlc/mcp-advisor"].';
+function pinnedSpec(version) {
+    return version && version !== '0.0.0'
+        ? `@ai-sdlc/mcp-advisor@${version}`
+        : '@ai-sdlc/mcp-advisor';
+}
+function standardEntry(version, env) {
     const entry = {
         command: 'npx',
-        args: ['-y', '@ai-sdlc/mcp-advisor'],
+        args: ['-y', pinnedSpec(version)],
     };
     if (env)
         entry.env = env;
     return entry;
 }
-function vscodeEntry(env) {
+function vscodeEntry(version, env) {
     const entry = {
         type: 'stdio',
         command: 'npx',
-        args: ['-y', '@ai-sdlc/mcp-advisor'],
+        args: ['-y', pinnedSpec(version)],
     };
     if (env)
         entry.env = env;
@@ -39,6 +64,7 @@ const AGENT_SPECS = [
         entryFn: standardEntry,
         configDir: '.cursor',
         binary: 'cursor',
+        requiresOptIn: true,
     },
     {
         name: 'VS Code',
@@ -66,31 +92,67 @@ function hasBinary(name) {
         return false;
     }
 }
-export function detectAgents(projectDir, options) {
+function hasUserCursorDir() {
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (!home)
+        return false;
+    return existsSync(join(home, '.cursor'));
+}
+export function detectAgentsDetailed(projectDir, options) {
     const detected = [];
+    const skipped = [];
     const env = options?.isWorkspace ? { AI_SDLC_WORKSPACE: '.' } : undefined;
+    const pinVersion = options?.pinVersion;
     for (const spec of AGENT_SPECS) {
         if (spec.alwaysDetect) {
             detected.push({
                 name: spec.name,
                 configPath: spec.configPath,
                 configKey: spec.configKey,
-                serverEntry: spec.entryFn(env),
+                serverEntry: spec.entryFn(pinVersion, env),
             });
             continue;
         }
         const hasDir = spec.configDir ? existsSync(join(projectDir, spec.configDir)) : false;
         const hasBin = spec.binary ? hasBinary(spec.binary) : false;
+        if (spec.requiresOptIn) {
+            // For Cursor specifically: explicit --cursor flag, OR a project-local
+            // .cursor/ dir, OR a user-global ~/.cursor/ presence. Just having
+            // `cursor` on PATH is no longer sufficient (too noisy on dev boxes
+            // where Cursor is installed but not used per-project).
+            const userOptIn = options?.cursorOptIn === true;
+            if (userOptIn || hasDir || hasUserCursorDir()) {
+                detected.push({
+                    name: spec.name,
+                    configPath: spec.configPath,
+                    configKey: spec.configKey,
+                    serverEntry: spec.entryFn(pinVersion, env),
+                });
+            }
+            else {
+                skipped.push({
+                    name: spec.name,
+                    reason: 'no .cursor/ directory in project or $HOME; pass --cursor to install Cursor MCP config',
+                });
+            }
+            continue;
+        }
         if (hasDir || hasBin) {
             detected.push({
                 name: spec.name,
                 configPath: spec.configPath,
                 configKey: spec.configKey,
-                serverEntry: spec.entryFn(env),
+                serverEntry: spec.entryFn(pinVersion, env),
             });
         }
     }
-    return detected;
+    return { detected, skipped };
+}
+/**
+ * Backwards-compatible wrapper. New code should prefer detectAgentsDetailed.
+ */
+export function detectAgents(projectDir, options) {
+    return detectAgentsDetailed(projectDir, options).detected;
 }
 export function installMcpServer(projectDir, agent, dryRun) {
     const fullPath = join(projectDir, agent.configPath);
@@ -110,6 +172,13 @@ export function installMcpServer(projectDir, agent, dryRun) {
         if (!dryRun) {
             section['ai-sdlc'] = agent.serverEntry;
             existing[agent.configKey] = section;
+            // Top-level pin-comment: standard convention is a single
+            // `_aiSdlcComment` key at the root of the document, not inside each
+            // server entry. We add it on first write but never overwrite an
+            // existing top-level value (caller may have customised it).
+            if (!('_aiSdlcComment' in existing)) {
+                existing._aiSdlcComment = PIN_OPT_OUT_COMMENT;
+            }
             writeFileSync(fullPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
         }
         return 'merged';
@@ -120,6 +189,7 @@ export function installMcpServer(projectDir, agent, dryRun) {
             mkdirSync(dir, { recursive: true });
         }
         const config = {
+            _aiSdlcComment: PIN_OPT_OUT_COMMENT,
             [agent.configKey]: {
                 'ai-sdlc': agent.serverEntry,
             },

package/dist/cli/formatters/table.js

@@ -37,7 +37,12 @@ export function formatTable(data) {
             lines.push('Health Check');
             lines.push('─'.repeat(40));
             lines.push(`Config:      ${data.configValid ? 'valid' : 'INVALID'}`);
-            lines.push(`State Store: ${data.stateStoreConnected ? 'connected' : 'not configured'}`);
+            // AISDLC-78: the previous "not configured" string read like a setup
+            // failure to fresh users. The state store is created on demand by
+            // the first pipeline run; explicitly flag deferred initialization.
+            lines.push(`State Store: ${data.stateStoreConnected
+                ? 'connected'
+                : 'deferred (initializes on first pipeline run; pass --init-state to create now)'}`);
             const errors = data.errors;
             if (errors.length > 0) {
                 lines.push('');
@@ -65,8 +70,16 @@ export function formatTable(data) {
                 for (const agent of agents) {
                     const total = agent.totalTasks;
                     const success = agent.successCount;
+                    const declaredOnly = agent.declaredOnly === true;
                     const pct = total > 0 ? `${Math.round((success / total) * 100)}%` : '-';
-                    const lastTask = agent.lastTaskAt ? agent.lastTaskAt.split('T')[0] : '-';
+                    // AISDLC-78 (AC #10): mark declared-but-not-executed rows so a
+                    // fresh-install user sees their `agent-role.yaml` declarations
+                    // even before the first pipeline run populates the ledger.
+                    const lastTask = declaredOnly
+                        ? '(declared, not yet executed)'
+                        : agent.lastTaskAt
+                            ? agent.lastTaskAt.split('T')[0]
+                            : '-';
                     lines.push(String(agent.agentName ?? '').padEnd(20) +
                         String(agent.currentLevel ?? 0).padEnd(7) +
                         String(total).padEnd(7) +