@stackwright-pro/mcp 0.2.0-alpha.61 → 0.2.0-alpha.68

package/dist/server.js

@@ -1331,6 +1331,13 @@ function answersToManifestFormat(answers, questions) {
   return result;
 }
 
+// src/validation.ts
+var SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
+var SAFE_QUESTION_ID = /^[a-z0-9][a-z0-9-]{0,63}$/i;
+function isValidPhase(phase) {
+  return SAFE_PHASE.test(phase);
+}
+
 // src/tools/questions.ts
 var ManifestQuestionSchema = import_zod8.z.object({
   id: import_zod8.z.string(),
@@ -1365,7 +1372,6 @@ function registerQuestionTools(server2) {
     },
     async ({ phase, questions, answers }) => {
       let resolvedQuestions;
-      const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
       if (!SAFE_PHASE.test(phase)) {
         return {
           content: [
@@ -1467,7 +1473,6 @@ function registerQuestionTools(server2) {
     "Returns the next unanswered question for a phase as a plain JSON object \u2014 one question at a time. Returns { done: true } when all questions are answered or the phase has no questions. Call this in a loop: present the question in plain chat, get user reply, call record_answer, repeat.",
     { phase: import_zod8.z.string().describe('Phase name e.g. "designer", "api", "auth"') },
     async ({ phase }) => {
-      const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
       if (!SAFE_PHASE.test(phase)) {
         return {
           content: [
@@ -1532,7 +1537,6 @@ function registerQuestionTools(server2) {
       answer: import_zod8.z.string().describe("The user's free-text answer")
     },
     async ({ phase, questionId, answer }) => {
-      const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
       if (!SAFE_PHASE.test(phase)) {
         return {
           content: [
@@ -1541,7 +1545,7 @@ function registerQuestionTools(server2) {
           isError: true
         };
       }
-      if (!/^[a-z0-9][a-z0-9-]{0,63}$/i.test(questionId)) {
+      if (!SAFE_QUESTION_ID.test(questionId)) {
         return {
           content: [
             { type: "text", text: JSON.stringify({ error: "Invalid questionId" }) }
@@ -1694,14 +1698,78 @@ function handleSaveManifest(input) {
   }
 }
 function handleSavePhaseAnswers(input) {
+  if (!isValidPhase(input.phase)) {
+    return {
+      text: JSON.stringify({
+        success: false,
+        error: `Invalid phase name: "${input.phase.slice(0, 50)}". Must be lowercase alphanumeric with hyphens, max 31 chars.`
+      }),
+      isError: true
+    };
+  }
+  for (let i = 0; i < input.rawAnswers.length; i++) {
+    const a = input.rawAnswers[i];
+    if (!a.question_header || a.question_header.trim().length === 0) {
+      return {
+        text: JSON.stringify({
+          success: false,
+          error: `rawAnswers[${i}].question_header is empty \u2014 every answer must have a non-empty question_header.`
+        }),
+        isError: true
+      };
+    }
+    if (!a.selected_options || a.selected_options.length === 0) {
+      return {
+        text: JSON.stringify({
+          success: false,
+          error: `rawAnswers[${i}].selected_options is empty for question_header "${a.question_header}" \u2014 every answer must have at least one selected option.`
+        }),
+        isError: true
+      };
+    }
+  }
+  if (input.questions && input.questions.length > 0 && input.rawAnswers.length === 0) {
+    return {
+      text: JSON.stringify({
+        success: false,
+        error: `${input.questions.length} questions provided but rawAnswers is empty \u2014 this is a malformed payload. If the phase truly has no questions, omit the questions parameter.`
+      }),
+      isError: true
+    };
+  }
   const cwd = input._cwd ?? process.cwd();
   const dir = (0, import_path3.join)(cwd, ".stackwright", "answers");
   const filePath = (0, import_path3.join)(dir, `${input.phase}.json`);
   try {
     (0, import_fs3.mkdirSync)(dir, { recursive: true });
+    const warnings = [];
     let answers;
     if (input.questions && input.questions.length > 0) {
-      answers = answersToManifestFormat(input.rawAnswers, input.questions);
+      try {
+        answers = answersToManifestFormat(input.rawAnswers, input.questions);
+      } catch (mapErr) {
+        answers = {};
+        warnings.push(
+          `Reverse-mapping threw (${mapErr instanceof Error ? mapErr.message : String(mapErr)}) \u2014 falling back to direct key mapping.`
+        );
+      }
+      if (Object.keys(answers).length === 0 && input.rawAnswers.length > 0) {
+        answers = Object.fromEntries(
+          input.rawAnswers.map((a) => [
+            a.question_header,
+            a.selected_options.length > 1 ? a.selected_options : a.selected_options[0] ?? ""
+          ])
+        );
+        warnings.push(
+          `Reverse-mapping produced empty answers despite ${input.rawAnswers.length} rawAnswers \u2014 used direct key mapping as fallback. Ensure question_header values match the manifest header format (e.g. "DESI-1", not descriptive keys).`
+        );
+      }
+      const requiredCount = input.questions.filter((q) => q.required !== false).length;
+      if (input.rawAnswers.length < requiredCount) {
+        warnings.push(
+          `Only ${input.rawAnswers.length} answers provided for ${requiredCount} required questions (${input.questions.length} total) \u2014 answers may be incomplete.`
+        );
+      }
     } else {
       answers = Object.fromEntries(
         input.rawAnswers.map((a) => [a.question_header, a.selected_options[0] ?? ""])
@@ -1728,7 +1796,8 @@ function handleSavePhaseAnswers(input) {
       text: JSON.stringify({
         success: true,
         path: filePath,
-        answersCount: Object.keys(answers).length
+        answersCount: Object.keys(answers).length,
+        ...warnings.length > 0 ? { warnings } : {}
       }),
       isError: false
     };
@@ -1875,15 +1944,31 @@ function registerOrchestrationTools(server2) {
       rawAnswers: jsonCoerce(
         import_zod9.z.array(
           import_zod9.z.object({
-            question_header: import_zod9.z.string(),
-            selected_options: import_zod9.z.array(import_zod9.z.string()),
+            question_header: import_zod9.z.string().min(1, "question_header must not be empty"),
+            selected_options: import_zod9.z.array(import_zod9.z.string()).min(1, "selected_options must have at least one entry"),
             other_text: import_zod9.z.string().nullable().optional()
           })
         )
       ).describe(
         "Answers as returned by ask_user_question \u2014 pass the native array, not a JSON string"
       ),
-      questions: jsonCoerce(import_zod9.z.array(import_zod9.z.any()).optional()).describe(
+      questions: jsonCoerce(
+        import_zod9.z.array(
+          import_zod9.z.object({
+            id: import_zod9.z.string(),
+            question: import_zod9.z.string(),
+            type: import_zod9.z.string(),
+            options: import_zod9.z.array(import_zod9.z.object({ label: import_zod9.z.string(), value: import_zod9.z.string() })).optional(),
+            required: import_zod9.z.boolean().optional(),
+            default: import_zod9.z.union([import_zod9.z.string(), import_zod9.z.boolean(), import_zod9.z.array(import_zod9.z.string())]).optional(),
+            help: import_zod9.z.string().optional(),
+            dependsOn: import_zod9.z.object({
+              questionId: import_zod9.z.string(),
+              value: import_zod9.z.union([import_zod9.z.string(), import_zod9.z.array(import_zod9.z.string())])
+            }).optional()
+          }).passthrough()
+        ).optional()
+      ).describe(
         "Original manifest questions for label\u2192value reverse-mapping \u2014 pass the native array, not a JSON string"
       )
     },
@@ -2285,12 +2370,13 @@ var PHASE_DEPENDENCIES = {
   // workflow states as trigger sources. Produces OpenAPI specs consumed
   // by pages and dashboard for typed data wiring.
   services: ["api", "workflow"],
-  // pages/dashboard: now also depend on services for typed endpoint wiring
-  // via the OpenAPI specs that services produces.
-  // 'api' is still transitive through 'data'; auth removed — page-otter has
-  // graceful fallback and reads role names from workflow artifacts instead
-  pages: ["designer", "theme", "data", "services"],
-  dashboard: ["designer", "theme", "data", "services"],
+  // pages/dashboard: depend on services for typed endpoint wiring (OpenAPI
+  // specs) and on geo so the specialist prompt includes geo-manifest.json
+  // — page/dashboard otters see which page slugs are already claimed and
+  // won't attempt to overwrite them (swp-73c). 'api' is still transitive
+  // through 'data'; auth removed — page-otter has graceful fallback.
+  pages: ["designer", "theme", "data", "services", "geo"],
+  dashboard: ["designer", "theme", "data", "services", "geo"],
   // auth is the penultimate phase — runs after all content-producing phases
   // so it can read pages, dashboard, workflow, and geo artifacts for route
   // protection and RBAC wiring. Skipped upstream phases still satisfy deps
@@ -2326,7 +2412,7 @@ var PHASE_TO_OTTER2 = {
   polish: "stackwright-pro-polish-otter",
   geo: "stackwright-pro-geo-otter"
 };
-function isValidPhase(phase) {
+function isValidPhase2(phase) {
   return PHASE_ORDER.includes(phase);
 }
 function defaultPhaseStatus() {
@@ -2422,7 +2508,7 @@ function handleGetPipelineState(_cwd) {
 }
 function handleSetPipelineState(input) {
   const cwd = input._cwd ?? process.cwd();
-  if (input.phase && !isValidPhase(input.phase)) {
+  if (input.phase && !isValidPhase2(input.phase)) {
     return {
       text: JSON.stringify({
         error: true,
@@ -2441,6 +2527,28 @@ function handleSetPipelineState(input) {
       isError: true
     };
   }
+  if (input.updates && input.updates.length > 0) {
+    for (const update of input.updates) {
+      if (!isValidPhase2(update.phase)) {
+        return {
+          text: JSON.stringify({
+            error: true,
+            message: `Invalid phase in batch update: ${update.phase}. Valid phases are: ${PHASE_ORDER.join(", ")}`
+          }),
+          isError: true
+        };
+      }
+      if (!VALID_FIELDS.includes(update.field)) {
+        return {
+          text: JSON.stringify({
+            error: true,
+            message: `Invalid field in batch update: ${update.field}. Valid fields are: ${VALID_FIELDS.join(", ")}`
+          }),
+          isError: true
+        };
+      }
+    }
+  }
   try {
     const state = readState(cwd);
     if (input.status) {
@@ -2460,6 +2568,16 @@ function handleSetPipelineState(input) {
       }
       state.currentPhase = phase;
     }
+    if (input.updates && input.updates.length > 0) {
+      for (const update of input.updates) {
+        if (!state.phases[update.phase]) {
+          state.phases[update.phase] = defaultPhaseStatus();
+        }
+        const batchPhaseState = state.phases[update.phase];
+        batchPhaseState[update.field] = update.value;
+        state.currentPhase = update.phase;
+      }
+    }
     writeState(cwd, state);
     return { text: JSON.stringify(state), isError: false };
   } catch (err) {
@@ -2469,7 +2587,7 @@ function handleSetPipelineState(input) {
 function handleCheckExecutionReady(_cwd, phase) {
   const cwd = _cwd ?? process.cwd();
   if (phase) {
-    if (!isValidPhase(phase)) {
+    if (!isValidPhase2(phase)) {
       return {
         text: JSON.stringify({
           error: true,
@@ -2617,7 +2735,7 @@ function handleListArtifacts(_cwd) {
 function handleWritePhaseQuestions(input) {
   const cwd = input._cwd ?? process.cwd();
   const { phase, responseText } = input;
-  if (!isValidPhase(phase)) {
+  if (!isValidPhase2(phase)) {
     return {
       text: JSON.stringify({ error: true, message: `Unknown phase: ${phase}` }),
       isError: true
@@ -2675,7 +2793,7 @@ function handleWritePhaseQuestions(input) {
 function handleBuildSpecialistPrompt(input) {
   const cwd = input._cwd ?? process.cwd();
   const { phase } = input;
-  if (!isValidPhase(phase)) {
+  if (!isValidPhase2(phase)) {
     return {
       text: JSON.stringify({ error: true, message: `Unknown phase: ${phase}` }),
       isError: true
@@ -2768,6 +2886,18 @@ ${JSON.stringify(content, null, 2)}`
     if (buildContextText) {
       parts.push("BUILD_CONTEXT:", buildContextText, "");
     }
+    if (phase === "auth") {
+      const initContextPath = (0, import_path5.join)(cwd, ".stackwright", "init-context.json");
+      if ((0, import_fs5.existsSync)(initContextPath)) {
+        try {
+          const initContext = JSON.parse(safeReadSync(initContextPath));
+          if (initContext.devOnly === true || initContext.nonInteractive === true) {
+            answers["devOnly"] = true;
+          }
+        } catch {
+        }
+      }
+    }
     parts.push("ANSWERS:", JSON.stringify(answers, null, 2));
     if (artifactSections.length > 0) {
       parts.push("", "UPSTREAM ARTIFACTS:", "", ...artifactSections);
@@ -3050,6 +3180,12 @@ var PHASE_ARTIFACT_SCHEMA = {
         protectedRoutes: ["/dashboard/:path*", "/procurement/:path*"],
         auditEnabled: true,
         auditRetentionDays: 90
+      },
+      // devScripts is OPTIONAL — only present when devOnly: true was used
+      // Polish otter and foreman MUST check devScripts.written before referencing scripts
+      devScripts: {
+        written: true,
+        scripts: { "dev:admin": "MOCK_USER=admin next dev" }
       }
     },
     null,
@@ -3061,7 +3197,12 @@ var PHASE_ARTIFACT_SCHEMA = {
       generatedBy: "stackwright-pro-polish-otter",
       landingPage: { slug: "", rewritten: true },
       navigation: { itemCount: 5, items: ["/dashboard", "/equipment", "/workflows"] },
-      gettingStarted: "<rewritten|redirected|not-found>"
+      gettingStarted: "<rewritten|redirected|not-found>",
+      scaffoldCleanup: {
+        deleted: ["content/posts/getting-started.yaml"],
+        rewritten: ["app/not-found.tsx"],
+        skipped: []
+      }
     },
     null,
     2
@@ -3070,7 +3211,7 @@ var PHASE_ARTIFACT_SCHEMA = {
 function handleValidateArtifact(input) {
   const cwd = input._cwd ?? process.cwd();
   const { phase, responseText, artifact: directArtifact } = input;
-  if (!isValidPhase(phase)) {
+  if (!isValidPhase2(phase)) {
     return {
       text: JSON.stringify({ error: true, message: `Unknown phase: ${phase}` }),
       isError: true
@@ -3218,7 +3359,16 @@ function registerPipelineTools(server2) {
       status: import_zod11.z.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
       incrementRetry: boolCoerce(import_zod11.z.boolean().optional()).describe(
         "Bump retryCount by 1 \u2014 must be a JSON boolean"
-      )
+      ),
+      updates: jsonCoerce(
+        import_zod11.z.array(
+          import_zod11.z.object({
+            phase: import_zod11.z.string(),
+            field: import_zod11.z.enum(["questionsCollected", "answered", "executed", "artifactWritten"]),
+            value: import_zod11.z.boolean()
+          })
+        ).optional()
+      ).describe("Batch updates \u2014 apply multiple field changes in one atomic read\u2192modify\u2192write")
     },
     async (args) => res(
       handleSetPipelineState({
@@ -3226,7 +3376,8 @@ function registerPipelineTools(server2) {
         ...args.field != null ? { field: args.field } : {},
         ...args.value != null ? { value: args.value } : {},
         ...args.status != null ? { status: args.status } : {},
-        ...args.incrementRetry != null ? { incrementRetry: args.incrementRetry } : {}
+        ...args.incrementRetry != null ? { incrementRetry: args.incrementRetry } : {},
+        ...args.updates != null ? { updates: args.updates } : {}
       })
     )
   );
@@ -3262,7 +3413,6 @@ function registerPipelineTools(server2) {
     },
     async ({ phase, responseText, questions }) => {
       if (phase && questions && Array.isArray(questions)) {
-        const SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
         if (!SAFE_PHASE.test(phase)) {
           return {
             content: [
@@ -3347,6 +3497,16 @@ var OTTER_WRITE_ALLOWLISTS = {
       prefix: ".env",
       suffix: "",
       description: "Dotenv files (.env, .env.local, .env.production, etc.)"
+    },
+    {
+      prefix: "lib/mock-auth",
+      suffix: ".ts",
+      description: "Mock auth module (DEV_ONLY_MODE role updates)"
+    },
+    {
+      prefix: "package.json",
+      suffix: ".json",
+      description: "Project package.json (DEV_ONLY_MODE script cleanup)"
     }
   ],
   "stackwright-pro-data-otter": [
@@ -3384,7 +3544,8 @@ var OTTER_WRITE_ALLOWLISTS = {
     },
     { prefix: "pages/", suffix: "/content.yml", description: "Landing page content" },
     { prefix: "pages/", suffix: "/content.yaml", description: "Landing page content" },
-    { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Polish artifact" }
+    { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Polish artifact" },
+    { prefix: "README.md", suffix: "", description: "Project README rewrite" }
   ],
   "stackwright-services-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Services config artifact" },
@@ -3404,7 +3565,9 @@ var PROTECTED_PATH_PREFIXES = [
   ".stackwright/artifacts/signatures.json",
   // artifact signature manifest
   ".stackwright/questions/",
-  ".stackwright/answers/"
+  ".stackwright/answers/",
+  ".stackwright/page-registry.json"
+  // page ownership — managed by safe_write internally
 ];
 var MAX_SAFE_WRITE_BYTES_JSON = 512 * 1024;
 var MAX_SAFE_WRITE_BYTES_YAML = 256 * 1024;
@@ -3418,6 +3581,58 @@ function getMaxBytesForPath(filePath) {
     return { limit: MAX_SAFE_WRITE_BYTES_ENV, label: "env" };
   return { limit: MAX_SAFE_WRITE_BYTES_DEFAULT, label: "default" };
 }
+var PAGE_REGISTRY_FILE = ".stackwright/page-registry.json";
+function extractPageSlug(filePath) {
+  const match = (0, import_path6.normalize)(filePath).match(/^pages\/(.+?)\/content\.ya?ml$/);
+  return match?.[1] ?? null;
+}
+function extractContentTypes(yamlContent) {
+  const typePattern = /^\s*-?\s*type:\s*(\S+)/gm;
+  const types = [];
+  let m;
+  while ((m = typePattern.exec(yamlContent)) !== null) {
+    const typeName = m[1];
+    if (typeName && !types.includes(typeName)) {
+      types.push(typeName);
+    }
+  }
+  return types.length > 0 ? types : ["unknown"];
+}
+function readPageRegistry(cwd) {
+  const regPath = (0, import_path6.join)(cwd, PAGE_REGISTRY_FILE);
+  if (!(0, import_fs6.existsSync)(regPath)) return {};
+  try {
+    const stat = (0, import_fs6.lstatSync)(regPath);
+    if (stat.isSymbolicLink()) return {};
+    return JSON.parse((0, import_fs6.readFileSync)(regPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writePageRegistry(cwd, registry) {
+  const dir = (0, import_path6.join)(cwd, ".stackwright");
+  (0, import_fs6.mkdirSync)(dir, { recursive: true });
+  const regPath = (0, import_path6.join)(cwd, PAGE_REGISTRY_FILE);
+  if ((0, import_fs6.existsSync)(regPath)) {
+    const stat = (0, import_fs6.lstatSync)(regPath);
+    if (stat.isSymbolicLink()) {
+      throw new Error("Refusing to write page registry through symlink");
+    }
+  }
+  (0, import_fs6.writeFileSync)(regPath, JSON.stringify(registry, null, 2) + "\n", { encoding: "utf-8" });
+}
+function checkPageOwnership(cwd, slug, callerOtter) {
+  const registry = readPageRegistry(cwd);
+  const existing = registry[slug];
+  if (!existing || existing.claimedBy === callerOtter) {
+    return { allowed: true };
+  }
+  return {
+    allowed: false,
+    owner: existing.claimedBy,
+    contentTypes: existing.contentTypes
+  };
+}
 function checkPathAllowed(callerOtter, filePath) {
   const normalized = (0, import_path6.normalize)(filePath);
   if (normalized.includes("..")) {
@@ -3459,6 +3674,16 @@ function checkPathAllowed(callerOtter, filePath) {
           continue;
         }
       }
+      if (rule.prefix === "lib/mock-auth" && rule.suffix === ".ts") {
+        if (normalized !== "lib/mock-auth.ts") {
+          continue;
+        }
+      }
+      if (rule.prefix === "package.json" && rule.suffix === ".json") {
+        if (normalized !== "package.json") {
+          continue;
+        }
+      }
       return { allowed: true, rule: rule.description };
     }
   }
@@ -3584,11 +3809,38 @@ function handleSafeWrite(input) {
     };
     return { text: JSON.stringify(result), isError: true };
   }
+  const pageSlug = extractPageSlug(normalized);
+  if (pageSlug) {
+    const ownership = checkPageOwnership(cwd, pageSlug, callerOtter);
+    if (!ownership.allowed) {
+      const result = {
+        success: false,
+        error: `Page slug "${pageSlug}" is already claimed by ${ownership.owner} (content types: ${ownership.contentTypes.join(", ")}). Use a different slug or coordinate with the owning otter.`,
+        callerOtter,
+        attemptedPath: filePath,
+        allowedPaths: []
+      };
+      return { text: JSON.stringify(result), isError: true };
+    }
+  }
   try {
     if (createDirectories) {
       (0, import_fs6.mkdirSync)((0, import_path6.dirname)(fullPath), { recursive: true });
     }
     (0, import_fs6.writeFileSync)(fullPath, content, { encoding: "utf-8" });
+    if (pageSlug) {
+      try {
+        const registry = readPageRegistry(cwd);
+        registry[pageSlug] = {
+          slug: pageSlug,
+          claimedBy: callerOtter,
+          contentTypes: extractContentTypes(content),
+          writtenAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        writePageRegistry(cwd, registry);
+      } catch {
+      }
+    }
     const result = {
       success: true,
       path: normalized,
@@ -3855,10 +4107,232 @@ ${routeLines}
 ${auditSection}
 `;
 }
+function generateDevOnlyMiddlewareContent(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+  const rbacBlock = `  rbac: {
+    roles: ${JSON.stringify(roles)},
+    defaultRole: '${defaultRole}',
+    hierarchy: ${JSON.stringify(hierarchy, null, 4)},
+  },`;
+  const auditBlock = `  audit: {
+    enabled: ${auditEnabled},
+    retentionDays: ${auditRetentionDays},
+  },`;
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const configBlock = `export const config = {
+  matcher: ${JSON.stringify(protectedRoutes)},
+};`;
+  const devHeader = [
+    "// middleware.ts \u2014 generated by @stackwright-pro/auth-nextjs (dev-only mock)",
+    "//   DEV ONLY \u2014 uses mock authentication from lib/mock-auth.ts",
+    "// Do NOT deploy to production.",
+    "import { createProMiddleware } from '@stackwright-pro/auth-nextjs';",
+    "import { mockAuthProvider } from './lib/mock-auth';"
+  ].join("\n");
+  if (method === "cac") {
+    const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
+    const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
+    const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
+    const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
+    return `${devHeader}
+
+export const middleware = createProMiddleware({
+  method: 'cac',
+  cac: {
+    caBundle: '${caBundle}',
+    edipiLookup: '${edipiLookup}',
+    ocspEndpoint: '${ocspEndpoint}',
+    certHeader: '${certHeader}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  if (method === "oidc") {
+    const scopes2 = params.oidcScopes ?? "openid profile email";
+    const roleClaim = params.oidcRoleClaim ?? "roles";
+    return `${devHeader}
+
+export const middleware = createProMiddleware({
+  method: 'oidc',
+  oidc: {
+    discoveryUrl: 'https://dev-mock-oidc/.well-known/openid-configuration',
+    clientId: 'dev-mock-client',
+    clientSecret: 'dev-mock-secret',
+    scopes: '${scopes2}',
+    roleClaim: '${roleClaim}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+  }
+  const scopes = params.oauth2Scopes ?? "read write";
+  return `${devHeader}
+
+export const middleware = createProMiddleware({
+  method: 'oauth2',
+  oauth2: {
+    authorizationUrl: 'https://dev-mock-oauth2/authorize',
+    tokenUrl: 'https://dev-mock-oauth2/token',
+    clientId: 'dev-mock-client',
+    clientSecret: 'dev-mock-secret',
+    scopes: '${scopes}',
+    provider: mockAuthProvider,
+  },
+${rbacBlock}
+${auditBlock}
+${routesBlock}
+});
+
+${configBlock}
+`;
+}
+function generateDevOnlyYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
+  const rbacSection = `  rbac:
+    roles:
+${rolesToYaml(roles, "      ")}
+    defaultRole: ${defaultRole}
+    hierarchy:
+${hierarchyToYaml(hierarchy, "      ")}`;
+  const auditSection = `  audit:
+    enabled: ${auditEnabled}
+    retentionDays: ${auditRetentionDays}`;
+  const routeLines = protectedRoutes.map((r) => `    - pattern: ${r}
+      requiredRole: ${defaultRole}`).join("\n");
+  const providerLine = params.provider ? `  provider: ${params.provider}
+` : "";
+  if (method === "cac") {
+    const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
+    const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
+    const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
+    const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
+    return `auth:
+  method: cac
+  devOnly: true
+${providerLine}  middleware: ./middleware.ts
+  cac:
+    caBundle: ${caBundle}
+    edipiLookup: ${edipiLookup}
+    ocspEndpoint: ${ocspEndpoint}
+    certHeader: ${certHeader}
+${rbacSection}
+  protectedRoutes:
+${routeLines}
+${auditSection}
+`;
+  }
+  if (method === "oidc") {
+    const scopes2 = params.oidcScopes ?? "openid profile email";
+    const roleClaim = params.oidcRoleClaim ?? "roles";
+    return `auth:
+  method: oidc
+  devOnly: true
+${providerLine}  middleware: ./middleware.ts
+  oidc:
+    discoveryUrl: https://dev-mock-oidc/.well-known/openid-configuration
+    clientId: dev-mock-client
+    clientSecret: dev-mock-secret
+    scopes: ${scopes2}
+    roleClaim: ${roleClaim}
+${rbacSection}
+  protectedRoutes:
+${routeLines}
+${auditSection}
+`;
+  }
+  const scopes = params.oauth2Scopes ?? "read write";
+  return `auth:
+  method: oauth2
+  devOnly: true
+${providerLine}  middleware: ./middleware.ts
+  oauth2:
+    authorizationUrl: https://dev-mock-oauth2/authorize
+    tokenUrl: https://dev-mock-oauth2/token
+    clientId: dev-mock-client
+    clientSecret: dev-mock-secret
+    scopes: ${scopes}
+${rbacSection}
+  protectedRoutes:
+${routeLines}
+${auditSection}
+`;
+}
+function deriveDevKey(roleName) {
+  const segment = roleName.split("_")[0];
+  return (segment ?? roleName).toLowerCase();
+}
+function generateMockAuthContent(roles, mockUsers) {
+  const entries = [];
+  const scriptLines = [];
+  for (let i = 0; i < roles.length; i++) {
+    const role = roles[i];
+    const devKey = deriveDevKey(role);
+    const persona = mockUsers?.[i];
+    const name = persona?.name ?? `Dev ${role}`;
+    const email = persona?.email ?? `dev-${devKey}@example.mil`;
+    const edipi = String(i + 1).padStart(10, "0");
+    entries.push(`  ${devKey}: {
+    id: 'mock-${devKey}-${String(i + 1).padStart(3, "0")}',
+    name: '${name}',
+    email: '${email}',
+    roles: ['${role}'],
+    edipi: '${edipi}',
+  }`);
+    scriptLines.push(` *   pnpm dev:${devKey}   \u2014 ${name}`);
+  }
+  return `/**
+ * Mock authentication for development mode.
+ *
+ * DEV_ONLY_MODE \u2014 no real auth provider. Select a persona via MOCK_USER env var
+ * or use the convenience scripts in package.json:
+${scriptLines.join("\n")}
+ */
+
+export const MOCK_USERS = {
+${entries.join(",\n")}
+} as const;
+
+export type MockRole = keyof typeof MOCK_USERS;
+
+export function getMockUser(role?: string) {
+  const key = (role ?? process.env.MOCK_USER) as MockRole | undefined;
+  if (!key) return null;
+  return MOCK_USERS[key] ?? null;
+}
+
+export function mockAuthProvider() {
+  return getMockUser();
+}
+`;
+}
+function updatePackageJsonScripts(existingJson, roles, mockUsers) {
+  const pkg = JSON.parse(existingJson);
+  const scripts = pkg.scripts ?? {};
+  delete scripts["dev:admin"];
+  delete scripts["dev:analyst"];
+  delete scripts["dev:viewer"];
+  for (let i = 0; i < roles.length; i++) {
+    const devKey = deriveDevKey(roles[i]);
+    scripts[`dev:${devKey}`] = `MOCK_USER=${devKey} next dev`;
+  }
+  pkg.scripts = scripts;
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
 async function configureAuthHandler(params, cwd) {
   const {
     method,
     provider,
+    devOnly = false,
+    mockUsers,
     rbacRoles = ["SUPER_ADMIN", "ADMIN", "ANALYST"],
     auditEnabled = true,
     auditRetentionDays = 90,
@@ -3888,7 +4362,16 @@ async function configureAuthHandler(params, cwd) {
   }
   const filesWritten = [];
   try {
-    const middlewareContent = generateMiddlewareContent(
+    const middlewareContent = devOnly ? generateDevOnlyMiddlewareContent(
+      method,
+      params,
+      roles,
+      defaultRole,
+      hierarchy,
+      auditEnabled,
+      auditRetentionDays,
+      protectedRoutes
+    ) : generateMiddlewareContent(
       method,
       params,
       roles,
@@ -3912,30 +4395,87 @@ async function configureAuthHandler(params, cwd) {
       isError: true
     };
   }
-  try {
-    const envBlock = generateEnvBlock(method, params);
-    const envPath = (0, import_path7.join)(cwd, ".env.example");
-    if ((0, import_fs7.existsSync)(envPath)) {
-      const existing = (0, import_fs7.readFileSync)(envPath, "utf8");
-      (0, import_fs7.writeFileSync)(envPath, existing.trimEnd() + "\n\n" + envBlock, "utf8");
-    } else {
-      (0, import_fs7.writeFileSync)(envPath, envBlock, "utf8");
+  if (!devOnly) {
+    try {
+      const envBlock = generateEnvBlock(method, params);
+      const envPath = (0, import_path7.join)(cwd, ".env.example");
+      if ((0, import_fs7.existsSync)(envPath)) {
+        const existing = (0, import_fs7.readFileSync)(envPath, "utf8");
+        (0, import_fs7.writeFileSync)(envPath, existing.trimEnd() + "\n\n" + envBlock, "utf8");
+      } else {
+        (0, import_fs7.writeFileSync)(envPath, envBlock, "utf8");
+      }
+      filesWritten.push(".env.example");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: false, error: `Failed writing .env.example: ${msg}` })
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+  if (devOnly) {
+    try {
+      const mockAuthDir = (0, import_path7.join)(cwd, "lib");
+      (0, import_fs7.mkdirSync)(mockAuthDir, { recursive: true });
+      const mockAuthContent = generateMockAuthContent(roles, mockUsers);
+      (0, import_fs7.writeFileSync)((0, import_path7.join)(mockAuthDir, "mock-auth.ts"), mockAuthContent, "utf8");
+      filesWritten.push("lib/mock-auth.ts");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: `Failed writing lib/mock-auth.ts: ${msg}`
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    try {
+      const pkgPath = (0, import_path7.join)(cwd, "package.json");
+      if ((0, import_fs7.existsSync)(pkgPath)) {
+        const existingPkg = (0, import_fs7.readFileSync)(pkgPath, "utf8");
+        const updatedPkg = updatePackageJsonScripts(existingPkg, roles, mockUsers);
+        (0, import_fs7.writeFileSync)(pkgPath, updatedPkg, "utf8");
+        filesWritten.push("package.json");
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              success: false,
+              error: `Failed updating package.json: ${msg}`
+            })
+          }
+        ],
+        isError: true
+      };
     }
-    filesWritten.push(".env.example");
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ success: false, error: `Failed writing .env.example: ${msg}` })
-        }
-      ],
-      isError: true
-    };
   }
   try {
-    const authYaml = generateYamlBlock(
+    const authYaml = devOnly ? generateDevOnlyYamlBlock(
+      method,
+      params,
+      roles,
+      defaultRole,
+      hierarchy,
+      auditEnabled,
+      auditRetentionDays,
+      protectedRoutes
+    ) : generateYamlBlock(
       method,
       params,
       roles,
@@ -3978,7 +4518,21 @@ async function configureAuthHandler(params, cwd) {
           rbacDefaultRole: defaultRole,
           protectedRoutesCount: protectedRoutes.length,
           filesWritten,
-          securityWarning
+          securityWarning,
+          ...devOnly ? {
+            devScripts: {
+              written: filesWritten.includes("package.json"),
+              scripts: filesWritten.includes("package.json") ? Object.fromEntries(
+                roles.map((r) => {
+                  const k = deriveDevKey(r);
+                  return [`dev:${k}`, `MOCK_USER=${k} next dev`];
+                })
+              ) : {},
+              ...filesWritten.includes("package.json") ? {} : {
+                warning: "package.json not found \u2014 dev scripts were not written. Run the auth phase again after scaffolding creates package.json."
+              }
+            }
+          } : {}
         })
       }
     ]
@@ -4017,7 +4571,9 @@ function registerAuthTools(server2) {
       // Routes
       protectedRoutes: jsonCoerce(import_zod13.z.array(import_zod13.z.string()).optional()),
       // Injection for tests
-      _cwd: import_zod13.z.string().optional()
+      _cwd: import_zod13.z.string().optional(),
+      devOnly: boolCoerce(import_zod13.z.boolean().optional()),
+      mockUsers: jsonCoerce(import_zod13.z.array(import_zod13.z.object({ name: import_zod13.z.string(), email: import_zod13.z.string() })).optional())
     },
     async (params) => {
       const cwd = params._cwd ?? process.cwd();
@@ -4037,15 +4593,15 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "8a6ee02cfe7fede3ca708d05b8b46824eb71f60c7f474b6edf9599da77f779b2"
+    "c3be215f05cc48ec51ed75541184b89a8ac123463b80fe02f2adb6c1b5163853"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "f5a83b74ad7c44edc6f39b45a568fa122d82aa4788f741ce14614da56d4e29a4"
+    "9c319d311801730e8dc9bc142eebb8fc5a7f48da48fa0b8d8c3b7431652447be"
   ],
   [
     "stackwright-pro-data-otter.json",
-    "c406e1c775bcb1f2b038b40a92d9bd23172b40d774fc0fa50bad4c9714f53445"
+    "4d9369277685a4acc484116920c9622ad8a1838012a493fcfe42a6ae5abe53cf"
   ],
   [
     "stackwright-pro-designer-otter.json",
@@ -4053,35 +4609,35 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-domain-expert-otter.json",
-    "bfe5c167d73fef3f2ef280fff56dcb552073c218e1394a43ecf983a03169ed55"
+    "41e3a5838f05f6a51ed272860dd2d5b1df1f20bfc847eb8f39be109b89738e99"
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "ab38ef53b95ec610a38b2866d78a135cbec16d257a9b35d7e46e2fee2d4de235"
+    "5f18e37ee3f2064c62a2d01dfc541285f27e5762d0b1011e2a37a48af96c74c8"
   ],
   [
     "stackwright-pro-geo-otter.json",
-    "6eb7ecf97254dbd79c09ad24348bf16001423cce9585c14bef81afd67b7b901b"
+    "ff1191af8108cc70c09afe6a99b008dcb46f71e20f884da1ee424e431868a1b6"
   ],
   [
     "stackwright-pro-page-otter.json",
-    "9a5672f0758c81539337d86955e2892cd412547b4f111c2aa098eed1e62d7626"
+    "1dcdf866be76d18f3aa2a9e56b8bf57a3d43477b43c410eb6d1feac0e7683658"
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "d31116995fdb417798af6056efd03bb1c71e0891371aba1774d283c03c9d77e8"
+    "72a52901b4781c9f0be97024ba6e19415cdfbd92369d9274aa3abe7efd208bc8"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "08bb04009fdfb8743b10ac4d503cbaddaf8d7c804ba9b606aaed9cc516fd8e93"
+    "e8530a1146abc57eb31d2f036ba057d5eae7d4a2d9dca00e415d1c352ef4c5b5"
   ],
   [
     "stackwright-pro-workflow-otter.json",
-    "c90d6773b2287aa9a640c2715ca0e75f44c13e99fddcfb89ced36603f38930ce"
+    "e02c1a5f492dd6b11f68e293d92f5f661dbb22e57570dcf133a9d0ffc7a8be7d"
   ],
   [
     "stackwright-services-otter.json",
-    "4893a596d187110124f78336ee91184a51b3c8d980c455382fe481adb9b487b5"
+    "b8a252d6a2c5090138899925d3ea95bf3339b6e49adc276a1f5f7304b4ae5134"
   ]
 ]);
 Object.freeze(_checksums);
@@ -4791,6 +5347,182 @@ function registerTypeSchemasTool(server2) {
   );
 }
 
+// src/tools/scaffold-cleanup.ts
+var import_fs10 = require("fs");
+var import_path10 = require("path");
+var SCAFFOLD_FILES_TO_DELETE = [
+  "content/posts/getting-started.yaml",
+  "content/posts/hello-world.yaml"
+];
+var SCAFFOLD_DIRS_TO_PRUNE = [
+  "content/posts"
+  // Don't prune 'content' — user may have other content directories
+];
+var NOT_FOUND_PATH = "app/not-found.tsx";
+var FALLBACK_COLORS = {
+  background: "#ffffff",
+  foreground: "#171717",
+  primary: "#525252",
+  mutedForeground: "#737373"
+};
+function readThemeColors(cwd) {
+  const tokenPath = (0, import_path10.join)(cwd, ".stackwright", "artifacts", "theme-tokens.json");
+  if (!(0, import_fs10.existsSync)(tokenPath)) return { ...FALLBACK_COLORS };
+  const stat = (0, import_fs10.lstatSync)(tokenPath);
+  if (stat.isSymbolicLink()) return { ...FALLBACK_COLORS };
+  try {
+    const raw = JSON.parse((0, import_fs10.readFileSync)(tokenPath, "utf-8"));
+    const css = raw?.cssVariables ?? {};
+    const toHsl = (hslValue) => {
+      if (!hslValue || typeof hslValue !== "string") return null;
+      return `hsl(${hslValue})`;
+    };
+    return {
+      background: toHsl(css["--background"]) ?? FALLBACK_COLORS.background,
+      foreground: toHsl(css["--foreground"]) ?? FALLBACK_COLORS.foreground,
+      primary: toHsl(css["--primary"]) ?? FALLBACK_COLORS.primary,
+      mutedForeground: toHsl(css["--muted-foreground"]) ?? FALLBACK_COLORS.mutedForeground
+    };
+  } catch {
+    return { ...FALLBACK_COLORS };
+  }
+}
+function generateNotFoundPage(colors) {
+  return `export default function NotFound() {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        minHeight: '100vh',
+        backgroundColor: '${colors.background}',
+        color: '${colors.foreground}',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        padding: '2rem',
+        textAlign: 'center',
+      }}
+    >
+      <h1 style={{ fontSize: '4rem', fontWeight: 700, margin: 0, color: '${colors.primary}' }}>
+        404
+      </h1>
+      <p style={{ fontSize: '1.25rem', color: '${colors.mutedForeground}', marginTop: '0.5rem' }}>
+        Page not found
+      </p>
+      <a
+        href="/"
+        style={{
+          marginTop: '2rem',
+          padding: '0.75rem 1.5rem',
+          backgroundColor: '${colors.primary}',
+          color: '${colors.background}',
+          borderRadius: '0.5rem',
+          textDecoration: 'none',
+          fontSize: '0.875rem',
+          fontWeight: 500,
+        }}
+      >
+        Go Home
+      </a>
+    </div>
+  );
+}
+`;
+}
+function isSafePath(fullPath) {
+  if (!(0, import_fs10.existsSync)(fullPath)) return true;
+  const stat = (0, import_fs10.lstatSync)(fullPath);
+  return !stat.isSymbolicLink();
+}
+function isDirEmpty(dirPath) {
+  if (!(0, import_fs10.existsSync)(dirPath)) return false;
+  const stat = (0, import_fs10.lstatSync)(dirPath);
+  if (!stat.isDirectory()) return false;
+  return (0, import_fs10.readdirSync)(dirPath).length === 0;
+}
+function handleCleanupScaffold(_cwd) {
+  const cwd = _cwd ?? process.cwd();
+  const result = {
+    deleted: [],
+    rewritten: [],
+    skipped: [],
+    errors: [],
+    prunedDirs: []
+  };
+  for (const relPath of SCAFFOLD_FILES_TO_DELETE) {
+    const fullPath = (0, import_path10.join)(cwd, relPath);
+    if (!(0, import_fs10.existsSync)(fullPath)) {
+      result.skipped.push(relPath);
+      continue;
+    }
+    if (!isSafePath(fullPath)) {
+      result.errors.push(`Refusing to delete symlink: ${relPath}`);
+      continue;
+    }
+    try {
+      (0, import_fs10.unlinkSync)(fullPath);
+      result.deleted.push(relPath);
+    } catch (err) {
+      result.errors.push(`Failed to delete ${relPath}: ${String(err)}`);
+    }
+  }
+  for (const relDir of SCAFFOLD_DIRS_TO_PRUNE) {
+    const fullDir = (0, import_path10.join)(cwd, relDir);
+    if (!(0, import_fs10.existsSync)(fullDir)) continue;
+    if (!isSafePath(fullDir)) {
+      result.errors.push(`Refusing to prune symlink directory: ${relDir}`);
+      continue;
+    }
+    if (isDirEmpty(fullDir)) {
+      try {
+        (0, import_fs10.rmdirSync)(fullDir);
+        result.prunedDirs.push(relDir);
+      } catch (err) {
+        result.errors.push(`Failed to prune directory ${relDir}: ${String(err)}`);
+      }
+    }
+  }
+  {
+    const fullPath = (0, import_path10.join)(cwd, NOT_FOUND_PATH);
+    if (!(0, import_fs10.existsSync)(fullPath)) {
+      result.skipped.push(NOT_FOUND_PATH);
+    } else if (!isSafePath(fullPath)) {
+      result.errors.push(`Refusing to rewrite symlink: ${NOT_FOUND_PATH}`);
+    } else {
+      try {
+        const colors = readThemeColors(cwd);
+        const content = generateNotFoundPage(colors);
+        const dir = (0, import_path10.dirname)(fullPath);
+        (0, import_fs10.mkdirSync)(dir, { recursive: true });
+        (0, import_fs10.writeFileSync)(fullPath, content, "utf-8");
+        result.rewritten.push(NOT_FOUND_PATH);
+      } catch (err) {
+        result.errors.push(`Failed to rewrite ${NOT_FOUND_PATH}: ${String(err)}`);
+      }
+    }
+  }
+  return {
+    text: JSON.stringify(result),
+    isError: false
+  };
+}
+function registerScaffoldCleanupTools(server2) {
+  const DESC = "Deterministic scaffold remnant cleanup \u2014 removes stale OSS scaffold files after raft run.";
+  server2.tool(
+    "stackwright_pro_cleanup_scaffold",
+    `Remove/rewrite stale scaffold files (blog posts, hardcoded not-found page) after the raft pipeline completes. ${DESC}`,
+    {},
+    async () => {
+      const r = handleCleanupScaffold();
+      return {
+        content: [{ type: "text", text: r.text }],
+        isError: r.isError
+      };
+    }
+  );
+}
+
 // package.json
 var package_default = {
   dependencies: {
@@ -4814,7 +5546,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.61",
+  version: "0.2.0-alpha.68",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -4868,6 +5600,7 @@ registerIntegrityTools(server);
 registerArtifactSigningTools(server);
 registerDomainTools(server);
 registerTypeSchemasTool(server);
+registerScaffoldCleanupTools(server);
 async function main() {
   const transport = new import_stdio.StdioServerTransport();
   try {