@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/testing/cli/scaffold-tests-from-ac/generate.ts

@@ -0,0 +1,190 @@
+/**
+ * cli:scaffold-tests-from-ac — generate.ts
+ *
+ * Pure code-emission. Takes parsed UCs and a spec → returns GeneratedFile[].
+ * No filesystem (index.ts writes), no LLM.
+ *
+ * One file per section that has ≥ 1 AC. Layout:
+ *
+ *   Tests/{ModuleP}/Acceptance/{SectionP}AcceptanceTests.cs
+ *
+ * Each AC becomes ONE [Fact] with:
+ *   - [Trait("Category","Acceptance")] [Trait("Module",…)] [Trait("AC", <globalId>)]
+ *   - Method name AC_NN_{slug-of-first-words}
+ *   - Verbatim AC text in a // comment
+ *   - // TODO[AC-NN]: ... + Assert.Fail("…") — Phase 5 fills this in.
+ *
+ * The TODO + Assert.Fail combo guarantees the test fails until a human/LLM
+ * implements the assertion. DEV-TEST-001 (Wave 3) audits that no `// TODO[AC-`
+ * remains on merge.
+ */
+
+import type {
+  GeneratedFile,
+  ScaffoldTestsFromAcSpec,
+  UcWithAc,
+} from './types.js'
+
+/** Convert kebab/snake `opportunites-rdv` → `OpportunitesRdv` (PascalCase). */
+function pascal(s: string): string {
+  return s
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map(p => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
+    .join('')
+}
+
+/** Slug AC text → snake-fragment usable in a C# method name. */
+function methodSlug(acText: string, maxWords = 7): string {
+  // Strip accents
+  const noAccents = acText.normalize('NFD').replace(/[̀-ͯ]/g, '')
+  // Keep alphanumerics and spaces; collapse the rest
+  const cleaned = noAccents
+    .replace(/[^a-zA-Z0-9 ]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  const words = cleaned.split(' ').slice(0, maxWords)
+  return words
+    .map(w => w.toLowerCase())
+    .join('_')
+    .slice(0, 80)
+}
+
+/** Compute the global AC reference `<UC-code>#AC-NN`. */
+function globalAcRef(ucCode: string, localId: string): string {
+  return `${ucCode}#${localId}`
+}
+
+/** Build the default namespace when none is supplied. */
+function defaultNamespace(appCode: string, module: string): string {
+  return `${pascal(appCode)}.Tests.${pascal(module)}.Acceptance`
+}
+
+/** Emit ONE Fact for ONE AC. Indented for the class body (4-space). */
+function emitFact(ucCode: string, ucTitle: string, localId: string, acText: string, moduleP: string): string {
+  const safeName = `${localId.replace('-', '_')}_${methodSlug(acText)}`.replace(/__+/g, '_')
+  const ref = globalAcRef(ucCode, localId)
+  // Escape embedded " in AC text for use inside a "..." literal
+  const acEscaped = acText.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+  return [
+    `    [Fact]`,
+    `    [Trait("Category", "Acceptance")]`,
+    `    [Trait("Module", "${moduleP}")]`,
+    `    [Trait("AC", "${ref}")]`,
+    `    public async Task ${safeName}()`,
+    `    {`,
+    `        // AC: ${acText}`,
+    `        // UC: ${ucCode} — ${ucTitle}`,
+    `        // TODO[${localId}]: implement assertion (see ${ucCode}#${localId} in use-case.md).`,
+    `        //   The /ba-develop Phase 5 subagent fills this body using:`,
+    `        //     - the AC text above (what to assert),`,
+    `        //     - the controller + DTO scaffolded in Phases 2-3,`,
+    `        //     - the WebApplicationFactory<Program> _factory fixture below.`,
+    `        await Task.CompletedTask;`,
+    `        Assert.Fail("${ref}: not yet implemented — Phase 5 must fill this body. Remove this line + the TODO once implemented.");`,
+    `    }`,
+    ``,
+  ].join('\n')
+}
+
+/** Emit ONE full test class (one section's UCs with ACs). */
+function emitTestClass(
+  ns: string,
+  moduleP: string,
+  sectionP: string,
+  ucsForSection: UcWithAc[]
+): string {
+  const className = `${sectionP}AcceptanceTests`
+  const header = [
+    `// <auto-generated by scaffold-tests-from-ac />`,
+    `// Each [Fact] in this file is one Acceptance Criterion (AC) declared under a UC`,
+    `// in .smartstack/ba/${moduleP.toLowerCase()}/${sectionP.toLowerCase().replace(/([A-Z])/g, '-$1').replace(/^-/, '')}/use-case.md.`,
+    `// Phase 5 of /ba-develop fills the // TODO[AC-NN] body with real assertions.`,
+    `// Audit DEV-TEST-001 (Wave 3) blocks merge if any // TODO[AC- marker remains.`,
+    ``,
+    `using System.Net;`,
+    `using System.Net.Http.Json;`,
+    `using FluentAssertions;`,
+    `using Microsoft.AspNetCore.Mvc.Testing;`,
+    `using Xunit;`,
+    ``,
+    `namespace ${ns};`,
+    ``,
+    `public class ${className} : IClassFixture<WebApplicationFactory<Program>>`,
+    `{`,
+    `    private readonly WebApplicationFactory<Program> _factory;`,
+    `    private readonly HttpClient _client;`,
+    ``,
+    `    public ${className}(WebApplicationFactory<Program> factory)`,
+    `    {`,
+    `        _factory = factory;`,
+    `        _client = factory.CreateClient();`,
+    `    }`,
+    ``,
+  ].join('\n')
+
+  const ucBlocks: string[] = []
+  for (const uc of ucsForSection) {
+    if (uc.acs.length === 0) continue
+    ucBlocks.push(`    // ==== ${uc.ucCode} — ${uc.title} ====\n`)
+    for (const ac of uc.acs) {
+      ucBlocks.push(emitFact(uc.ucCode, uc.title, ac.localId, ac.text, moduleP))
+    }
+  }
+
+  const footer = `}\n`
+  return header + ucBlocks.join('\n') + footer
+}
+
+export interface GenerateInput {
+  spec: ScaffoldTestsFromAcSpec
+  ucs: UcWithAc[]
+}
+
+export interface GenerateOutput {
+  files: GeneratedFile[]
+  ucsScanned: number
+  acsParsed: number
+  factsEmitted: number
+}
+
+/**
+ * Group UCs by section, emit one file per section that has ≥ 1 AC, return them.
+ * Caller (index.ts) writes them to disk (unless --dry-run).
+ */
+export function generate(input: GenerateInput): GenerateOutput {
+  const { spec, ucs } = input
+  const moduleP = pascal(spec.module)
+  const ns = spec.namespace ?? defaultNamespace(spec.appCode, spec.module)
+
+  // Group by section
+  const bySection = new Map<string, UcWithAc[]>()
+  for (const uc of ucs) {
+    const key = uc.sectionFolder
+    if (!bySection.has(key)) bySection.set(key, [])
+    bySection.get(key)!.push(uc)
+  }
+
+  const files: GeneratedFile[] = []
+  let factsEmitted = 0
+  for (const [sectionFolder, sectionUcs] of bySection.entries()) {
+    const totalAcs = sectionUcs.reduce((n, uc) => n + uc.acs.length, 0)
+    if (totalAcs === 0) continue
+    const sectionP = pascal(sectionFolder)
+    const content = emitTestClass(ns, moduleP, sectionP, sectionUcs)
+    const relPath = `Tests/${moduleP}/Acceptance/${sectionP}AcceptanceTests.cs`
+    files.push({ path: relPath, content })
+    factsEmitted += totalAcs
+  }
+
+  const acsParsed = ucs.reduce((n, uc) => n + uc.acs.length, 0)
+  return {
+    files,
+    ucsScanned: ucs.length,
+    acsParsed,
+    factsEmitted,
+  }
+}
+
+// Re-export helpers for tests
+export { pascal, methodSlug, globalAcRef, defaultNamespace }

package/templates/skills/development/testing/cli/scaffold-tests-from-ac/index.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * cli:scaffold-tests-from-ac — index.ts
+ *
+ * Reads `use-case.md` files under a BA module folder, emits one xUnit [Fact]
+ * skeleton per Acceptance Criterion (AC). Phase 5 of /ba-develop fills the
+ * TODO bodies; DEV-TEST-001 (Wave 3) audits coverage.
+ *
+ * Invocation:
+ *   npx tsx scaffold-tests-from-ac/index.ts \
+ *     --spec '{"moduleDir":"…","projectPath":"…","appCode":"crm","module":"pipeline"}' \
+ *     [--json]
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { findFiles } from '../../../../lib/fs.js'
+import { generate } from './generate.js'
+import { parseAcFromUseCaseMd } from './parse-ac.js'
+import type { ScaffoldTestsFromAcResult, UcWithAc } from './types.js'
+import { validate } from './validate.js'
+
+async function main(): Promise<void> {
+  const args = parseArgs({
+    options: {
+      spec: { type: 'string' },
+      json: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  })
+
+  if (!args.values.spec) {
+    console.error('Error: --spec is required')
+    process.exit(2)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(args.values.spec)
+  } catch {
+    console.error('Error: --spec must be valid JSON')
+    process.exit(2)
+  }
+
+  const validation = validate(raw)
+  if (!validation.valid) {
+    emit(args.values.json, {
+      success: false,
+      error: validation.errors.join('; '),
+      ucsScanned: 0,
+      acsParsed: 0,
+      factsEmitted: 0,
+      filesCreated: [],
+      warnings: validation.warnings,
+    })
+    process.exit(2)
+  }
+
+  const spec = validation.data!
+  const moduleDir = resolve(spec.moduleDir)
+  const projectPath = resolve(spec.projectPath)
+
+  // Find every use-case.md under <moduleDir>/<section>/...
+  // Uses lib/fs.findFiles (minimatch-based) for Node 18+ compat.
+  const absoluteMatches = await findFiles('**/use-case.md', { cwd: moduleDir })
+
+  const allUcs: UcWithAc[] = []
+  const warnings: string[] = [...validation.warnings]
+
+  for (const absolute of absoluteMatches) {
+    const rel = relative(moduleDir, absolute).replace(/\\/g, '/')
+    let content: string
+    try {
+      content = readFileSync(absolute, 'utf8')
+    } catch (err) {
+      warnings.push(`Cannot read ${rel}: ${(err as Error).message}`)
+      continue
+    }
+    const result = parseAcFromUseCaseMd(content, rel)
+    warnings.push(...result.warnings)
+    allUcs.push(...result.ucs)
+  }
+
+  const { files, ucsScanned, acsParsed, factsEmitted } = generate({ spec, ucs: allUcs })
+
+  const filesCreated: string[] = []
+  if (!spec.dryRun) {
+    for (const f of files) {
+      const absolute = join(projectPath, f.path)
+      mkdirSync(dirname(absolute), { recursive: true })
+      writeFileSync(absolute, f.content, 'utf8')
+      filesCreated.push(relative(projectPath, absolute).replace(/\\/g, '/'))
+    }
+  } else {
+    for (const f of files) filesCreated.push(f.path)
+  }
+
+  const result: ScaffoldTestsFromAcResult = {
+    success: true,
+    ucsScanned,
+    acsParsed,
+    factsEmitted,
+    filesCreated,
+    warnings,
+  }
+  emit(args.values.json, result)
+  process.exit(0)
+}
+
+function emit(json: boolean | undefined, payload: ScaffoldTestsFromAcResult): void {
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2))
+    return
+  }
+  if (!payload.success) {
+    console.error(`✗ ${payload.error ?? 'failed'}`)
+    return
+  }
+  console.log(`✓ scaffold-tests-from-ac:`)
+  console.log(`  UCs scanned   : ${payload.ucsScanned}`)
+  console.log(`  ACs parsed    : ${payload.acsParsed}`)
+  console.log(`  [Fact]s emitted: ${payload.factsEmitted}`)
+  console.log(`  Files created : ${payload.filesCreated.length}`)
+  for (const p of payload.filesCreated) console.log(`    + ${p}`)
+  if (payload.warnings.length > 0) {
+    console.log(`  Warnings:`)
+    for (const w of payload.warnings) console.log(`    ! ${w}`)
+  }
+}
+
+main().catch(err => {
+  console.error('Fatal:', (err as Error).message)
+  process.exit(2)
+})
+
+// Ensure existsSync is used (placeholder for future fs.access)
+void existsSync

package/templates/skills/development/testing/cli/scaffold-tests-from-ac/parse-ac.ts

@@ -0,0 +1,172 @@
+/**
+ * cli:scaffold-tests-from-ac — parse-ac.ts
+ *
+ * Pure parser for `use-case.md` → array of `UcWithAc`. No filesystem, no I/O.
+ * Reads ONE file's text + its source path metadata; the caller does the Glob.
+ *
+ * Grammar handled (see `_workflow/doc-templates.md`):
+ *
+ *   ### UC-{APP}-{MOD}-{SEC}-NNN — Title
+ *   - **Acteur principal** : …
+ *   …
+ *   - **Acceptance Criteria** :
+ *     - [ ] AC-01 — Assertion 1.
+ *     - [ ] AC-02 — Assertion 2.
+ *
+ * Tolerant of:
+ *   - missing `**Acceptance Criteria**` field (returns acs: [])
+ *   - extra whitespace
+ *   - the field appearing in any position among the UC bullets
+ *   - both 4-space and tabbed indentation under the AC field
+ *
+ * Strict on:
+ *   - `AC-NN` MUST match `^AC-\d{2}$` (UC-013 audit)
+ *   - `- [ ] AC-NN — …` separator is the em-dash ` — ` (U+2014, what
+ *     `/ba-create-use-case` writes) OR a plain ASCII ` - ` (graceful fallback)
+ */
+
+import type { Ac, UcWithAc } from './types.js'
+
+/** Extract the section folder code from a UC code (uppercase form → kebab). */
+function deriveSectionFolder(ucCode: string): string {
+  // UC-CRM-PIPELINE-OPPORTUNITES-001  →  ['UC','CRM','PIPELINE','OPPORTUNITES','001']
+  const parts = ucCode.split('-')
+  if (parts.length < 5) return ''
+  // section = part [3], kebab = lowercase with `_` → `-`
+  return parts[3]!.toLowerCase().replace(/_/g, '-')
+}
+
+/** Extract the SECTION_CODE (UPPERCASE) — segment [3] of UC-APP-MOD-SEC-NNN. */
+function deriveSectionCode(ucCode: string): string {
+  const parts = ucCode.split('-')
+  return parts.length >= 5 ? parts[3]! : ''
+}
+
+/** Match a UC heading and capture (code, title). */
+const UC_HEADING_RE = /^###\s+(UC-[A-Z0-9_]+-[A-Z0-9_]+-[A-Z0-9_]+-\d{3})\s+[—\-]\s+(.+?)\s*$/
+
+/** Match the `**Acceptance Criteria**` field opener. */
+const AC_FIELD_OPENER_RE = /^-\s*\*\*Acceptance\s+Criteria\*\*\s*:\s*$/i
+
+/** Match `**<Field>**` bullets that end the AC field block. */
+const FIELD_BULLET_RE = /^-\s*\*\*[^*]+\*\*\s*:/
+
+/**
+ * Match a single AC bullet :
+ *   `  - [ ] AC-NN — text`     (4 spaces, em-dash)
+ *   `\t- [x] AC-NN - text`     (tab, ASCII dash)
+ * Captures (localId, text).
+ */
+const AC_BULLET_RE = /^\s+-\s*\[[ xX]?\]\s*(AC-\d{2})\s+[—\-]\s+(.+?)\s*$/
+
+export interface ParseAcResult {
+  ucs: UcWithAc[]
+  warnings: string[]
+}
+
+/**
+ * Parse one `use-case.md` file content.
+ *
+ * @param text     - Raw markdown content of the file.
+ * @param relPath  - Source file path RELATIVE to moduleDir (e.g. `opportunites/use-case.md`).
+ *                   The section folder is taken from the first path segment.
+ */
+export function parseAcFromUseCaseMd(text: string, relPath: string): ParseAcResult {
+  const ucs: UcWithAc[] = []
+  const warnings: string[] = []
+
+  // Section folder is the path segment OWNING use-case.md
+  // e.g. `opportunites/use-case.md` → `opportunites`
+  // The UC heading will confirm via its 4th segment (UPPERCASE).
+  const pathSectionFolder = relPath.split(/[/\\]/).slice(-2, -1)[0] ?? ''
+
+  const lines = text.split(/\r?\n/)
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    const headingMatch = line.match(UC_HEADING_RE)
+    if (!headingMatch) {
+      i++
+      continue
+    }
+
+    const ucCode = headingMatch[1]!
+    const title = headingMatch[2]!
+    const sectionCode = deriveSectionCode(ucCode)
+    const derivedFolder = deriveSectionFolder(ucCode)
+
+    // Cross-check section folder consistency
+    if (derivedFolder && pathSectionFolder && derivedFolder !== pathSectionFolder) {
+      warnings.push(
+        `${relPath}: UC ${ucCode} declares section "${derivedFolder}" but lives under folder "${pathSectionFolder}"`
+      )
+    }
+
+    // Scan forward for the AC field within THIS UC's bullet block.
+    // Stop at next UC heading, next H1/H2 heading, or EOF.
+    let j = i + 1
+    let acs: Ac[] = []
+    let foundAcField = false
+    while (j < lines.length) {
+      const lj = lines[j]!
+      if (UC_HEADING_RE.test(lj) || /^#{1,2}\s/.test(lj)) break
+
+      if (AC_FIELD_OPENER_RE.test(lj)) {
+        foundAcField = true
+        // Consume bullets indented under this field
+        let k = j + 1
+        const seenIds = new Set<string>()
+        while (k < lines.length) {
+          const lk = lines[k]!
+          // Stop on next top-level UC bullet (- **Field**:) or UC heading or H1/H2
+          if (UC_HEADING_RE.test(lk) || /^#{1,2}\s/.test(lk)) break
+          if (FIELD_BULLET_RE.test(lk)) break
+          // Empty line: tolerate
+          if (lk.trim() === '') {
+            k++
+            continue
+          }
+          const acMatch = lk.match(AC_BULLET_RE)
+          if (acMatch) {
+            const localId = acMatch[1]!
+            const acText = acMatch[2]!
+            if (seenIds.has(localId)) {
+              warnings.push(`${relPath}: UC ${ucCode} duplicates ${localId}`)
+            } else {
+              seenIds.add(localId)
+              acs.push({ localId, text: acText })
+            }
+          } else if (/^\s+-/.test(lk)) {
+            // bullet that does not match AC-NN — flag as malformed
+            warnings.push(
+              `${relPath}: UC ${ucCode} has a malformed AC bullet: "${lk.trim()}". Expected "- [ ] AC-NN — text".`
+            )
+          }
+          k++
+        }
+        j = k
+        continue
+      }
+      j++
+    }
+
+    if (!foundAcField) {
+      warnings.push(
+        `${relPath}: UC ${ucCode} has no **Acceptance Criteria** field (will emit no [Fact]; audit UC-012 may flag this).`
+      )
+    }
+
+    ucs.push({
+      ucCode,
+      title,
+      sectionCode,
+      sectionFolder: derivedFolder || pathSectionFolder,
+      sourceFile: relPath,
+      acs,
+    })
+
+    i = j
+  }
+
+  return { ucs, warnings }
+}

package/templates/skills/development/testing/cli/scaffold-tests-from-ac/types.ts

@@ -0,0 +1,104 @@
+/**
+ * cli:scaffold-tests-from-ac — types.ts
+ *
+ * Generates ONE xUnit `[Fact]` per Acceptance Criterion (AC) declared under each
+ * use case in `.smartstack/ba/<APP>/<MODULE>/<section>/use-case.md`. The body is
+ * a structured TODO that the `/ba-develop` Phase 5 subagent fills in by reading
+ * the AC text + the entity DTO + the controller. The audit `DEV-TEST-001`
+ * (Wave 3) verifies no TODO remains on merge.
+ *
+ * Read the use-case.md format in
+ * `templates/skills/business-analyse/_workflow/doc-templates.md` (AC subsection).
+ *
+ * Zero MCP. Zero LLM at scaffold time — pure structural emission.
+ */
+
+import { z } from 'zod'
+
+/** A single `- [ ] AC-NN — <text>` bullet under a UC's `**Acceptance Criteria**` field. */
+export const AcSchema = z.object({
+  /** `AC-01`, `AC-02`, … — local to the parent UC, zero-padded 2 digits. */
+  localId: z.string().regex(/^AC-\d{2}$/, 'Expected AC-NN (2 digits)'),
+  /** Verbatim text after the ` — ` separator. */
+  text: z.string().min(1),
+})
+
+export type Ac = z.infer<typeof AcSchema>
+
+/** A `### UC-{APP}-{MOD}-{SEC}-NNN — Title` heading + its parsed ACs. */
+export const UcWithAcSchema = z.object({
+  /** Verbatim UC code from the heading (e.g. `UC-CRM-PIPELINE-OPPORTUNITES-001`). */
+  ucCode: z.string().regex(/^UC-[A-Z0-9_]+-[A-Z0-9_]+-[A-Z0-9_]+-\d{3}$/, 'Expected UC-{APP}-{MOD}-{SEC}-NNN'),
+  /** UC title (text after the ` — ` in the heading). */
+  title: z.string().min(1),
+  /** Section folder code in UPPERCASE (e.g. `OPPORTUNITES`) — derived from ucCode. */
+  sectionCode: z.string().min(1),
+  /** Section folder code in kebab-case (e.g. `opportunites`) — derived from path. */
+  sectionFolder: z.string().min(1),
+  /** Source file (relative to moduleDir) for traceability in errors. */
+  sourceFile: z.string().min(1),
+  /** ACs found under this UC (may be empty — Audit UC-012 warns on `user-goal` UCs). */
+  acs: z.array(AcSchema).default([]),
+})
+
+export type UcWithAc = z.infer<typeof UcWithAcSchema>
+
+export const ScaffoldTestsFromAcSpecSchema = z.object({
+  /**
+   * Absolute path to the BA module folder
+   * (e.g. `D:/project/.smartstack/ba/CRM/PIPELINE`). Glob is run against
+   * `<moduleDir>/<section>/use-case.md`.
+   */
+  moduleDir: z.string().min(1),
+
+  /**
+   * Absolute path to the generated-app root (where `*.Tests.csproj` lives).
+   * The CLI writes tests to `{projectPath}/Tests/{Module}/Acceptance/...`.
+   */
+  projectPath: z.string().min(1),
+
+  /** Lowercase application code (e.g. `crm`) — used to build the namespace prefix. */
+  appCode: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'Expected lowercase kebab appCode'),
+
+  /** Lowercase module code (e.g. `pipeline`). */
+  module: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/, 'Expected lowercase kebab module'),
+
+  /**
+   * Optional namespace prefix override. When absent, the CLI uses
+   * `{Pascal(appCode)}.Tests.{Pascal(module)}.Acceptance`.
+   */
+  namespace: z.string().optional(),
+
+  /**
+   * When true, the CLI parses + plans + returns the would-be file paths but
+   * writes nothing. Used by the dev orchestrator for pre-flight coverage checks.
+   */
+  dryRun: z.boolean().optional().default(false),
+})
+
+export type ScaffoldTestsFromAcSpec = z.infer<typeof ScaffoldTestsFromAcSpecSchema>
+
+/** One emitted .cs file. */
+export const GeneratedFileSchema = z.object({
+  path: z.string().min(1),
+  content: z.string(),
+})
+
+export type GeneratedFile = z.infer<typeof GeneratedFileSchema>
+
+export const ScaffoldTestsFromAcResultSchema = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+  /** Total UC headings scanned (across every section). */
+  ucsScanned: z.number(),
+  /** Total AC bullets parsed (across every UC). */
+  acsParsed: z.number(),
+  /** Total `[Fact]` methods emitted. */
+  factsEmitted: z.number(),
+  /** Test files emitted (one per section that has ≥1 UC with ≥1 AC). */
+  filesCreated: z.array(z.string()),
+  /** Non-fatal issues (e.g. UC without AC field, malformed bullets). */
+  warnings: z.array(z.string()),
+})
+
+export type ScaffoldTestsFromAcResult = z.infer<typeof ScaffoldTestsFromAcResultSchema>

package/templates/skills/development/testing/cli/scaffold-tests-from-ac/validate.ts

@@ -0,0 +1,57 @@
+/**
+ * cli:scaffold-tests-from-ac — validate.ts
+ *
+ * Two-stage: (a) Zod schema validation on the input spec,
+ * (b) Filesystem existence checks (moduleDir + projectPath must exist).
+ *
+ * Returns a {valid, errors[], warnings[], data} envelope. No side effects.
+ */
+
+import { existsSync, statSync } from 'node:fs'
+import { ScaffoldTestsFromAcSpecSchema, type ScaffoldTestsFromAcSpec } from './types.js'
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  data?: ScaffoldTestsFromAcSpec
+}
+
+export function validate(raw: unknown): ValidationResult {
+  // Stage A — Zod
+  const parsed = ScaffoldTestsFromAcSpecSchema.safeParse(raw)
+  if (!parsed.success) {
+    const errors = parsed.error.issues.map(i => `${i.path.join('.') || '(root)'}: ${i.message}`)
+    return { valid: false, errors, warnings: [] }
+  }
+  const spec = parsed.data
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // Stage B — Filesystem
+  if (!existsSync(spec.moduleDir)) {
+    errors.push(`moduleDir does not exist: ${spec.moduleDir}`)
+  } else if (!statSync(spec.moduleDir).isDirectory()) {
+    errors.push(`moduleDir is not a directory: ${spec.moduleDir}`)
+  }
+
+  if (!existsSync(spec.projectPath)) {
+    errors.push(`projectPath does not exist: ${spec.projectPath}`)
+  } else if (!statSync(spec.projectPath).isDirectory()) {
+    errors.push(`projectPath is not a directory: ${spec.projectPath}`)
+  }
+
+  // Soft check: namespace shape (informational)
+  if (spec.namespace && !/^[A-Z][A-Za-z0-9]*(\.[A-Z][A-Za-z0-9]*)+$/.test(spec.namespace)) {
+    warnings.push(
+      `namespace "${spec.namespace}" does not look like Pascal.Dot.Notation — accepted as-is, but emitted code may not compile.`
+    )
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    data: errors.length === 0 ? spec : undefined,
+  }
+}