sdd-cli 0.1.29 → 0.1.31

package/README.md

@@ -55,7 +55,7 @@ sdd-cli hello "create a calculator app"
 ## Global Flags
 
 - `--approve`, `--improve`, `--parallel`
-- `--non-interactive`, `--dry-run`, `--beginner`, `--from-step`
+- `--non-interactive`, `--dry-run`, `--beginner`, `--from-step`, `--iterations`
 - `--project`, `--output`, `--scope`, `--metrics-local`
 - `--provider`, `--gemini`, `--model`
 

package/dist/cli.js

@@ -85,6 +85,7 @@ program
     .option("--metrics-local", "Enable local opt-in telemetry snapshots in workspace/metrics")
     .option("--provider <name>", "AI provider: gemini|codex|auto", (0, providers_1.defaultProviderPreference)())
     .option("--model <name>", "AI model id (for providers that support model override)")
+    .option("--iterations <n>", "Autopilot improvement iterations (1-10)", "1")
     .option("--gemini", "Shortcut for --provider gemini");
 program.hook("preAction", (thisCommand, actionCommand) => {
     const config = (0, config_1.ensureConfig)();
@@ -109,7 +110,8 @@ program.hook("preAction", (thisCommand, actionCommand) => {
             : typeof opts.provider === "string"
                 ? opts.provider
                 : config.ai.preferred_cli,
-        model: typeof opts.model === "string" ? opts.model : config.ai.model
+        model: typeof opts.model === "string" ? opts.model : config.ai.model,
+        iterations: Number.parseInt(typeof opts.iterations === "string" ? opts.iterations : "1", 10)
     });
     process.env.SDD_GEMINI_MODEL = typeof opts.model === "string" ? opts.model : config.ai.model;
     const commandPath = typeof actionCommand.name === "function"
@@ -492,7 +494,7 @@ function normalizeArgv(argv) {
     if (args.length === 0) {
         return argv;
     }
-    const valueFlags = new Set(["--from-step", "--project", "--output", "--scope", "--provider", "--model"]);
+    const valueFlags = new Set(["--from-step", "--project", "--output", "--scope", "--provider", "--model", "--iterations"]);
     let positionalIndex = -1;
     for (let i = 0; i < args.length; i += 1) {
         const token = args[i];

package/dist/commands/digital-reviewers.d.ts

@@ -4,6 +4,14 @@ type ReviewerFinding = {
     severity: "high" | "medium";
     message: string;
 };
+export type UserStory = {
+    id: string;
+    priority: "P0" | "P1";
+    persona: string;
+    story: string;
+    acceptanceCriteria: string[];
+    sourceReviewer: string;
+};
 export type DigitalReviewResult = {
     passed: boolean;
     findings: ReviewerFinding[];
@@ -13,5 +21,9 @@ export type DigitalReviewResult = {
     summary: string;
 };
 export declare function runDigitalHumanReview(appDir: string, context?: LifecycleContext): DigitalReviewResult;
+export declare function convertFindingsToUserStories(findings: ReviewerFinding[]): UserStory[];
+export declare function storiesToDiagnostics(stories: UserStory[]): string[];
+export declare function writeUserStoriesBacklog(appDir: string, stories: UserStory[]): string | null;
+export declare function appendDigitalReviewRound(appDir: string, round: number, review: DigitalReviewResult, stories: UserStory[]): string | null;
 export declare function writeDigitalReviewReport(appDir: string, review: DigitalReviewResult): string | null;
 export {};

package/dist/commands/digital-reviewers.js

@@ -4,6 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runDigitalHumanReview = runDigitalHumanReview;
+exports.convertFindingsToUserStories = convertFindingsToUserStories;
+exports.storiesToDiagnostics = storiesToDiagnostics;
+exports.writeUserStoriesBacklog = writeUserStoriesBacklog;
+exports.appendDigitalReviewRound = appendDigitalReviewRound;
 exports.writeDigitalReviewReport = writeDigitalReviewReport;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -90,6 +94,30 @@ function hasUserFlowDocs(root, readme) {
     }
     return Boolean(findDoc(root, ["user-flow.md", "ux-notes.md", "experience.md"]));
 }
+function hasAccessibilityEvidence(root, readme) {
+    if (/\ba11y\b|\baccessibility\b|\bwcag\b|\bkeyboard\b/.test(readme)) {
+        return true;
+    }
+    return Boolean(findDoc(root, ["accessibility.md", "a11y.md"]));
+}
+function hasPerformanceEvidence(root, readme) {
+    if (/\bperformance\b|\blatency\b|\bthroughput\b|\bp95\b|\bp99\b/.test(readme)) {
+        return true;
+    }
+    return Boolean(findDoc(root, ["performance.md", "performance-budget.md", "scalability.md"]));
+}
+function hasSupportEvidence(root, readme) {
+    if (/\btroubleshoot\b|\bsupport\b|\bfaq\b/.test(readme)) {
+        return true;
+    }
+    return Boolean(findDoc(root, ["troubleshooting.md", "support.md", "faq.md"]));
+}
+function hasApiContracts(root) {
+    return Boolean(findDoc(root, ["openapi.yaml", "openapi.yml", "api-contract.md", "api.md"]));
+}
+function hasReleaseNotes(root) {
+    return Boolean(findDoc(root, ["release-notes.md", "changelog.md"]));
+}
 function parseThreshold() {
     const raw = Number.parseInt(process.env.SDD_DIGITAL_REVIEW_MIN_SCORE ?? "", 10);
     if (!Number.isFinite(raw)) {
@@ -179,6 +207,41 @@ function runDigitalHumanReview(appDir, context) {
             message: "User experience flow is unclear. Add user-flow/UX notes and acceptance of critical journeys."
         });
     }
+    if (!hasAccessibilityEvidence(appDir, readme)) {
+        findings.push({
+            reviewer: "accessibility_tester",
+            severity: "medium",
+            message: "Accessibility evidence missing. Add keyboard/contrast/screen-reader validation notes."
+        });
+    }
+    if (!hasPerformanceEvidence(appDir, readme)) {
+        findings.push({
+            reviewer: "performance_engineer",
+            severity: "medium",
+            message: "Performance expectations are unclear. Add performance budget and baseline measurements."
+        });
+    }
+    if (!hasSupportEvidence(appDir, readme)) {
+        findings.push({
+            reviewer: "support_agent",
+            severity: "medium",
+            message: "Support/troubleshooting guidance is missing for operators and end users."
+        });
+    }
+    if (!hasApiContracts(appDir)) {
+        findings.push({
+            reviewer: "integrator_partner",
+            severity: "medium",
+            message: "API contract/documentation missing. Add OpenAPI or API contract document for integrators."
+        });
+    }
+    if (!hasReleaseNotes(appDir)) {
+        findings.push({
+            reviewer: "release_manager",
+            severity: "medium",
+            message: "Release notes/changelog missing. Add release documentation for change visibility."
+        });
+    }
     if (hasSecretLeak(appDir)) {
         findings.push({
             reviewer: "security_reviewer",
@@ -227,6 +290,96 @@ function runDigitalHumanReview(appDir, context) {
         summary
     };
 }
+function slugReviewer(reviewer) {
+    return reviewer.replace(/[^a-z0-9]+/gi, "_").toLowerCase();
+}
+function acceptanceCriteriaFromFinding(finding) {
+    const base = finding.message.replace(/\.$/, "");
+    return [
+        `Given the generated app, when quality review runs, then ${base.toLowerCase()}.`,
+        "Given CI validation, when documentation/tests are checked, then evidence is discoverable and actionable."
+    ];
+}
+function convertFindingsToUserStories(findings) {
+    const deduped = new Map();
+    for (const finding of findings) {
+        const key = `${finding.reviewer}::${finding.message}`.toLowerCase();
+        if (!deduped.has(key)) {
+            deduped.set(key, finding);
+        }
+    }
+    let index = 1;
+    return [...deduped.values()].map((finding) => {
+        const id = `US-${String(index).padStart(3, "0")}`;
+        index += 1;
+        const persona = slugReviewer(finding.reviewer);
+        const priority = finding.severity === "high" ? "P0" : "P1";
+        return {
+            id,
+            priority,
+            persona,
+            sourceReviewer: finding.reviewer,
+            story: `As a ${persona}, I need ${finding.message.toLowerCase()} so that the delivery is production-ready.`,
+            acceptanceCriteria: acceptanceCriteriaFromFinding(finding)
+        };
+    });
+}
+function storiesToDiagnostics(stories) {
+    return stories.map((story) => `[UserStory:${story.id}][${story.priority}] ${story.story}`);
+}
+function writeUserStoriesBacklog(appDir, stories) {
+    if (!fs_1.default.existsSync(appDir)) {
+        return null;
+    }
+    const deployDir = path_1.default.join(appDir, "deploy");
+    fs_1.default.mkdirSync(deployDir, { recursive: true });
+    const jsonPath = path_1.default.join(deployDir, "digital-review-user-stories.json");
+    fs_1.default.writeFileSync(jsonPath, JSON.stringify({
+        generatedAt: new Date().toISOString(),
+        count: stories.length,
+        stories
+    }, null, 2), "utf-8");
+    const mdPath = path_1.default.join(deployDir, "digital-review-user-stories.md");
+    const lines = [
+        "# Digital Review User Stories",
+        "",
+        ...stories.flatMap((story) => [
+            `## ${story.id} (${story.priority})`,
+            `- Persona: ${story.persona}`,
+            `- Source reviewer: ${story.sourceReviewer}`,
+            `- Story: ${story.story}`,
+            "- Acceptance criteria:",
+            ...story.acceptanceCriteria.map((criterion) => `  - ${criterion}`),
+            ""
+        ])
+    ];
+    fs_1.default.writeFileSync(mdPath, `${lines.join("\n")}\n`, "utf-8");
+    return jsonPath;
+}
+function appendDigitalReviewRound(appDir, round, review, stories) {
+    if (!fs_1.default.existsSync(appDir)) {
+        return null;
+    }
+    const deployDir = path_1.default.join(appDir, "deploy");
+    fs_1.default.mkdirSync(deployDir, { recursive: true });
+    const reportPath = path_1.default.join(deployDir, "digital-review-rounds.json");
+    const existing = fs_1.default.existsSync(reportPath)
+        ? JSON.parse(fs_1.default.readFileSync(reportPath, "utf-8"))
+        : { rounds: [] };
+    const rounds = Array.isArray(existing.rounds) ? existing.rounds : [];
+    rounds.push({
+        round,
+        generatedAt: new Date().toISOString(),
+        summary: review.summary,
+        passed: review.passed,
+        score: review.score,
+        threshold: review.threshold,
+        findings: review.findings,
+        stories
+    });
+    fs_1.default.writeFileSync(reportPath, JSON.stringify({ rounds }, null, 2), "utf-8");
+    return reportPath;
+}
 function writeDigitalReviewReport(appDir, review) {
     if (!fs_1.default.existsSync(appDir)) {
         return null;

package/dist/commands/hello.js

@@ -128,6 +128,11 @@ async function runHello(input, runQuestions) {
     const dryRun = runtimeFlags.dryRun;
     const beginnerMode = runtimeFlags.beginner;
     const provider = runtimeFlags.provider;
+    const iterations = runtimeFlags.iterations;
+    if (!Number.isInteger(iterations) || iterations < 1 || iterations > 10) {
+        (0, errors_1.printError)("SDD-1005", "Invalid --iterations value. Use an integer between 1 and 10.");
+        return;
+    }
     console.log("Hello from sdd-cli.");
     console.log(`Workspace: ${workspace.root}`);
     if (beginnerMode) {
@@ -136,6 +141,7 @@ async function runHello(input, runQuestions) {
     if (autoGuidedMode) {
         printWhy("Auto-guided mode active: using current workspace defaults.");
         printWhy(`AI provider preference: ${provider ?? "gemini"}`);
+        printWhy(`Iterations configured: ${iterations}`);
     }
     else {
         const useWorkspace = await (0, prompt_1.confirm)("Use this workspace path? (y/n) ");
@@ -449,40 +455,50 @@ async function runHello(input, runQuestions) {
                 const digitalReviewDisabled = lifecycleDisabled || process.env.SDD_DISABLE_AI_AUTOPILOT === "1" || process.env.SDD_DISABLE_DIGITAL_REVIEW === "1";
                 if (!digitalReviewDisabled) {
                     const appDir = path_1.default.join(projectRoot, "generated-app");
-                    const parsedReviewAttempts = Number.parseInt(process.env.SDD_DIGITAL_REVIEW_MAX_ATTEMPTS ?? "", 10);
-                    const maxReviewAttempts = Number.isFinite(parsedReviewAttempts) && parsedReviewAttempts > 0 ? parsedReviewAttempts : 3;
-                    let review = (0, digital_reviewers_1.runDigitalHumanReview)(appDir, {
-                        goalText: text,
-                        intentSignals: intent.signals,
-                        intentDomain: intent.domain,
-                        intentFlow: intent.flow
-                    });
-                    const initialReviewReport = (0, digital_reviewers_1.writeDigitalReviewReport)(appDir, review);
-                    if (initialReviewReport) {
-                        printWhy(`Digital-review report: ${initialReviewReport}`);
-                    }
-                    if (!review.passed) {
-                        printWhy(`Digital human reviewers found delivery issues (${review.summary}). Applying targeted refinements.`);
+                    let deliveryApproved = false;
+                    for (let round = 1; round <= iterations; round += 1) {
+                        printWhy(`Iteration ${round}/${iterations}: running multi-persona digital review.`);
+                        let review = (0, digital_reviewers_1.runDigitalHumanReview)(appDir, {
+                            goalText: text,
+                            intentSignals: intent.signals,
+                            intentDomain: intent.domain,
+                            intentFlow: intent.flow
+                        });
+                        let stories = (0, digital_reviewers_1.convertFindingsToUserStories)(review.findings);
+                        const reviewPath = (0, digital_reviewers_1.writeDigitalReviewReport)(appDir, review);
+                        const storiesPath = (0, digital_reviewers_1.writeUserStoriesBacklog)(appDir, stories);
+                        (0, digital_reviewers_1.appendDigitalReviewRound)(appDir, round, review, stories);
+                        if (reviewPath) {
+                            printWhy(`Digital-review report: ${reviewPath}`);
+                        }
+                        if (storiesPath) {
+                            printWhy(`Digital-review user stories: ${storiesPath} (${stories.length} stories)`);
+                        }
+                        if (review.passed) {
+                            printWhy(`Iteration ${round}: digital reviewers approved (${review.summary}).`);
+                            deliveryApproved = true;
+                            continue;
+                        }
+                        printWhy(`Iteration ${round}: reviewers requested improvements (${review.summary}).`);
                         review.diagnostics.forEach((issue) => printWhy(`Reviewer issue: ${issue}`));
-                    }
-                    for (let attempt = 1; attempt <= maxReviewAttempts && !review.passed; attempt += 1) {
-                        const repair = (0, ai_autopilot_1.improveGeneratedApp)(appDir, text, provider, review.diagnostics, intent.domain);
+                        const storyDiagnostics = (0, digital_reviewers_1.storiesToDiagnostics)(stories);
+                        const repair = (0, ai_autopilot_1.improveGeneratedApp)(appDir, text, provider, [...review.diagnostics, ...storyDiagnostics, "Implement all prioritized user stories before next review."], intent.domain);
                         if (!repair.attempted || !repair.applied) {
-                            printWhy(`Digital-review repair attempt ${attempt} skipped: ${repair.reason || "unknown reason"}`);
+                            printWhy(`Iteration ${round}: repair skipped (${repair.reason || "unknown reason"}).`);
                             break;
                         }
-                        printWhy(`Digital-review repair attempt ${attempt} applied (${repair.fileCount} files).`);
+                        printWhy(`Iteration ${round}: repair applied (${repair.fileCount} files). Re-validating lifecycle.`);
                         lifecycle = (0, app_lifecycle_1.runAppLifecycle)(projectRoot, activeProject, {
                             goalText: text,
                             intentSignals: intent.signals,
                             intentDomain: intent.domain,
                             intentFlow: intent.flow
                         });
-                        lifecycle.summary.forEach((line) => printWhy(`Lifecycle (digital-review retry ${attempt}): ${line}`));
+                        lifecycle.summary.forEach((line) => printWhy(`Lifecycle (iteration ${round}): ${line}`));
                         if (!lifecycle.qualityPassed) {
+                            printWhy("Quality gates failed after story implementation. Applying one quality-repair pass.");
                             const qualityRepair = (0, ai_autopilot_1.improveGeneratedApp)(appDir, text, provider, lifecycle.qualityDiagnostics, intent.domain);
                             if (qualityRepair.attempted && qualityRepair.applied) {
-                                printWhy(`Quality regression repaired after digital review (${qualityRepair.fileCount} files). Re-validating delivery.`);
                                 lifecycle = (0, app_lifecycle_1.runAppLifecycle)(projectRoot, activeProject, {
                                     goalText: text,
                                     intentSignals: intent.signals,
@@ -492,7 +508,7 @@ async function runHello(input, runQuestions) {
                             }
                         }
                         if (!lifecycle.qualityPassed) {
-                            printWhy("Delivery regressed below lifecycle quality gates during digital-review iteration.");
+                            printWhy(`Iteration ${round}: lifecycle quality still failing.`);
                             continue;
                         }
                         review = (0, digital_reviewers_1.runDigitalHumanReview)(appDir, {
@@ -501,17 +517,23 @@ async function runHello(input, runQuestions) {
                             intentDomain: intent.domain,
                             intentFlow: intent.flow
                         });
+                        stories = (0, digital_reviewers_1.convertFindingsToUserStories)(review.findings);
                         (0, digital_reviewers_1.writeDigitalReviewReport)(appDir, review);
-                        if (!review.passed) {
-                            review.diagnostics.forEach((issue) => printWhy(`Reviewer issue (retry ${attempt}): ${issue}`));
+                        (0, digital_reviewers_1.writeUserStoriesBacklog)(appDir, stories);
+                        (0, digital_reviewers_1.appendDigitalReviewRound)(appDir, round, review, stories);
+                        if (review.passed) {
+                            printWhy(`Iteration ${round}: delivery improved and approved (${review.summary}).`);
+                            deliveryApproved = true;
+                        }
+                        else {
+                            printWhy(`Iteration ${round}: additional improvements still required (${review.summary}).`);
                         }
                     }
-                    if (!review.passed) {
-                        printWhy("Digital-review quality bar not met after refinement attempts.");
+                    if (!deliveryApproved) {
+                        printWhy("Digital-review quality bar not met after configured iterations.");
                         printRecoveryNext(activeProject, "finish", text);
                         return;
                     }
-                    printWhy(`Digital reviewers approved delivery quality (${review.summary}).`);
                 }
                 (0, local_metrics_1.recordActivationMetric)("completed", {
                     project: activeProject,

package/dist/context/flags.d.ts

@@ -12,6 +12,7 @@ export type RuntimeFlags = {
     metricsLocal?: boolean;
     provider?: string;
     model?: string;
+    iterations: number;
 };
 export declare function setFlags(next: Partial<RuntimeFlags>): void;
 export declare function getFlags(): RuntimeFlags;

package/dist/context/flags.js

@@ -15,7 +15,8 @@ const flags = {
     scope: undefined,
     metricsLocal: false,
     provider: process.env.SDD_AI_PROVIDER_DEFAULT ?? "gemini",
-    model: process.env.SDD_AI_MODEL_DEFAULT
+    model: process.env.SDD_AI_MODEL_DEFAULT,
+    iterations: 1
 };
 function setFlags(next) {
     if ("approve" in next) {
@@ -57,6 +58,10 @@ function setFlags(next) {
     if ("model" in next) {
         flags.model = typeof next.model === "string" ? next.model : flags.model;
     }
+    if ("iterations" in next) {
+        const raw = Number(next.iterations);
+        flags.iterations = Number.isFinite(raw) ? Math.trunc(raw) : flags.iterations;
+    }
 }
 function getFlags() {
     return { ...flags };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-cli",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "AI-orchestrated specification-driven delivery CLI that plans, validates, and ships production-ready software projects.",
   "keywords": [
     "cli",