@shahmarasy/prodo 0.1.0

package/src/cli.ts

@@ -0,0 +1,322 @@
+import { Command } from "commander";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadAgentCommandSet, resolveAgent } from "./agents";
+import { resolveAi, type SupportedAi } from "./agent-command-installer";
+import { listArtifactTypes } from "./artifact-registry";
+import { generateArtifact } from "./artifacts";
+import { runDoctor } from "./doctor";
+import { UserError } from "./errors";
+import { runHookPhase } from "./hook-executor";
+import { runInit } from "./init";
+import { finishInitInteractive, gatherInitSelections } from "./init-tui";
+import { runNormalize } from "./normalize";
+import { briefPath } from "./paths";
+import { type ArtifactType } from "./types";
+import { fileExists } from "./utils";
+import { runValidate } from "./validate";
+import { readCliVersion } from "./version";
+
+type RunOptions = {
+  forcedCommand?: string;
+  cwd?: string;
+  argv?: string[];
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string
+) => Promise<unknown>;
+
+function mapForcedCommand(forcedCommand: string): ArtifactType | "init" | "validate" | "normalize" | undefined {
+  if (forcedCommand === "prodo-init") return "init";
+  if (forcedCommand === "prodo-validate") return "validate";
+  if (forcedCommand === "prodo-normalize") return "normalize";
+  if (forcedCommand === "prodo-prd") return "prd";
+  if (forcedCommand === "prodo-workflow") return "workflow";
+  if (forcedCommand === "prodo-wireframe") return "wireframe";
+  if (forcedCommand === "prodo-stories") return "stories";
+  if (forcedCommand === "prodo-techspec") return "techspec";
+  return undefined;
+}
+
+async function runArtifactCommand(
+  type: ArtifactType,
+  opts: { from?: string; out?: string; agent?: string },
+  cwd: string,
+  log: (message: string) => void,
+  options?: { suggestValidate?: boolean }
+): Promise<void> {
+  await runHookPhase(cwd, `before_${type}`, log);
+  const agent = resolveAgent(opts.agent);
+  const file = await generateArtifact({
+    artifactType: type,
+    cwd,
+    normalizedBriefOverride: opts.from,
+    outPath: opts.out,
+    agent
+  });
+  const agentMsg = agent ? ` [agent=${agent}]` : "";
+  log(`${type.toUpperCase()} generated${agentMsg}: ${file}`);
+  if (options?.suggestValidate !== false) {
+    log("Tip: run `prodo validate` to check cross-artifact consistency.");
+  }
+  await runHookPhase(cwd, `after_${type}`, log);
+}
+
+type BriefSnapshot = {
+  hash: string;
+  mtimeMs: number;
+  size: number;
+};
+
+async function snapshotBrief(cwd: string): Promise<BriefSnapshot | null> {
+  const file = briefPath(cwd);
+  if (!(await fileExists(file))) return null;
+  const [raw, stat] = await Promise.all([fs.readFile(file), fs.stat(file)]);
+  return {
+    hash: createHash("sha256").update(raw).digest("hex"),
+    mtimeMs: stat.mtimeMs,
+    size: stat.size
+  };
+}
+
+async function withBriefReadOnlyGuard(cwd: string, task: () => Promise<void>): Promise<void> {
+  const before = await snapshotBrief(cwd);
+  await task();
+  const after = await snapshotBrief(cwd);
+  if (!before) return;
+  if (!after) {
+    throw new UserError("Input file `brief.md` was removed during execution. Input files are read-only.");
+  }
+  if (before.hash !== after.hash || before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+    throw new UserError("Input file `brief.md` was modified during execution. Input files are read-only.");
+  }
+}
+
+export async function runCli(options: RunOptions = {}): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const argv = options.argv ?? process.argv;
+  const out = options.log ?? console.log;
+  const err = options.error ?? console.error;
+  const forced = options.forcedCommand ? mapForcedCommand(options.forcedCommand) : undefined;
+
+  const program = new Command();
+  const version = await readCliVersion(cwd);
+  program
+    .name("prodo")
+    .description("CLI-first, prompt-powered product artifact kit")
+    .version(`prodo ${version}`, "-v, --version", "Show Prodo version")
+    .showHelpAfterError();
+  const artifactTypes = await listArtifactTypes(cwd);
+
+  program
+    .command("init [target]")
+    .option("--ai <name>", "agent integration: codex | gemini-cli | claude-cli")
+    .option("--lang <code>", "document language (e.g. en, tr)")
+    .option("--preset <name>", "preset to install during initialization")
+    .action(async (target, opts) => {
+      const projectRoot = path.resolve(cwd, target ?? ".");
+      const selected = await gatherInitSelections({
+        projectRoot,
+        aiInput: opts.ai,
+        langInput: opts.lang
+      });
+      const selectedAi = selected.ai as SupportedAi | undefined;
+
+      if (selected.interactive) {
+        const clack = (await dynamicImport("@clack/prompts")) as typeof import("@clack/prompts");
+        const s = clack.spinner();
+        s.start("Scaffolding Prodo workspace...");
+        const result = await runInit(projectRoot, {
+          ai: selectedAi,
+          lang: selected.lang,
+          preset: opts.preset,
+          script: selected.script
+        });
+        s.stop("Scaffold complete.");
+        await finishInitInteractive({
+          projectRoot,
+          settingsPath: result.settingsPath,
+          ai: selectedAi,
+          script: selected.script,
+          lang: selected.lang
+        });
+        return;
+      }
+
+      const result = await runInit(projectRoot, {
+        ai: selectedAi,
+        lang: selected.lang,
+        preset: opts.preset,
+        script: selected.script
+      });
+      out(`Initialized Prodo scaffold at ${path.join(projectRoot, ".prodo")}`);
+      if (selectedAi) {
+        out(`Agent command set installed for ${selectedAi}.`);
+        out(`Installed ${result.installedAgentFiles.length} command files.`);
+        out("Primary workflow: run `prodo generate` after editing brief.md.");
+        out("Advanced: artifact-level slash commands remain available when needed.");
+      } else {
+        out("No agent selected. Use `prodo generate` for end-to-end generation.");
+        out("Advanced commands are still available when needed.");
+      }
+      out(`Settings file: ${result.settingsPath}`);
+      out("Next: edit brief.md, then run `prodo generate`.");
+    });
+
+  program
+    .command("generate")
+    .description("Run end-to-end pipeline: normalize -> generate artifacts -> validate")
+    .option("--agent <name>", "agent profile: codex | gemini-cli | claude-cli")
+    .option("--strict", "treat validation warnings as errors")
+    .option("--report <path>", "validation report output path")
+    .action(async (opts) => {
+      if (opts.agent) resolveAgent(opts.agent);
+      await withBriefReadOnlyGuard(cwd, async () => {
+        await runHookPhase(cwd, "before_normalize", out);
+        const normalizedPath = await runNormalize({ cwd });
+        out(`Normalized brief written to: ${normalizedPath}`);
+        await runHookPhase(cwd, "after_normalize", out);
+
+        for (const type of artifactTypes) {
+          await runArtifactCommand(type, { from: normalizedPath, agent: opts.agent }, cwd, out, {
+            suggestValidate: false
+          });
+        }
+
+        await runHookPhase(cwd, "before_validate", out);
+        const result = await runValidate(cwd, {
+          strict: Boolean(opts.strict),
+          report: opts.report
+        });
+        out(`Validation report written to: ${result.reportPath}`);
+        if (!result.pass) {
+          throw new UserError("Validation failed. Review report and fix issues.");
+        }
+        out("Generation pipeline completed. Validation passed.");
+        await runHookPhase(cwd, "after_validate", out);
+      });
+    });
+
+  program
+    .command("normalize")
+    .description("Advanced: normalize brief without full pipeline")
+    .option("--brief <path>", "path to start brief markdown")
+    .option("--out <path>", "output normalized brief json path")
+    .option("--agent <name>", "agent profile: codex | gemini-cli | claude-cli")
+    .action(async (opts: { brief?: string; out?: string; agent?: string }) => {
+      if (opts.agent) resolveAgent(opts.agent);
+      await withBriefReadOnlyGuard(cwd, async () => {
+        await runHookPhase(cwd, "before_normalize", out);
+        const outPath = await runNormalize({
+          cwd,
+          brief: opts.brief,
+          out: opts.out
+        });
+        out(`Normalized brief written to: ${outPath}`);
+        await runHookPhase(cwd, "after_normalize", out);
+      });
+    });
+
+  program
+    .command("doctor")
+    .alias("check")
+    .description("Check local environment and toolchain readiness")
+    .action(async () => {
+      await runDoctor(cwd, out);
+    });
+
+  for (const type of artifactTypes) {
+    program
+      .command(type)
+      .description(`Advanced: generate only ${type} artifact`)
+      .option("--from <path>", "path to normalized-brief.json")
+      .option("--out <path>", "output file path")
+      .option("--agent <name>", "agent profile: codex | gemini-cli | claude-cli")
+      .action(async (opts: { from?: string; out?: string; agent?: string }) => {
+        await withBriefReadOnlyGuard(cwd, async () => {
+          await runArtifactCommand(type, opts, cwd, out);
+        });
+      });
+  }
+
+  program
+    .command("agent-commands")
+    .requiredOption("--agent <name>", "agent profile: codex | gemini-cli | claude-cli")
+    .action(async (opts) => {
+      const agent = resolveAgent(opts.agent);
+      if (!agent) throw new UserError("Agent is required.");
+      const set = await loadAgentCommandSet(cwd, agent);
+      out(`Agent: ${set.agent}`);
+      if (set.description) out(`Description: ${set.description}`);
+      out("");
+      out("Recommended sequence:");
+      for (const item of set.recommended_sequence ?? []) {
+        out(`- ${item.command}: ${item.purpose}`);
+      }
+      if (set.artifact_shortcuts) {
+        out("");
+        out("Artifact shortcuts:");
+        for (const [key, command] of Object.entries(set.artifact_shortcuts)) {
+          out(`- ${key}: ${command}`);
+        }
+      }
+    });
+
+  program
+    .command("validate")
+    .description("Advanced: run validation only")
+    .option("--strict", "treat warnings as errors")
+    .option("--report <path>", "report output path")
+    .option("--agent <name>", "agent profile: codex | gemini-cli | claude-cli")
+    .action(async (opts: { strict?: boolean; report?: string; agent?: string }) => {
+      if (opts.agent) resolveAgent(opts.agent);
+      await withBriefReadOnlyGuard(cwd, async () => {
+        await runHookPhase(cwd, "before_validate", out);
+        const result = await runValidate(cwd, {
+          strict: Boolean(opts.strict),
+          report: opts.report
+        });
+        out(`Validation report written to: ${result.reportPath}`);
+        if (!result.pass) {
+          throw new UserError("Validation failed. Review report and fix issues.");
+        }
+        out("Validation passed.");
+        await runHookPhase(cwd, "after_validate", out);
+      });
+    });
+
+  try {
+    if (forced) {
+      if (forced === "init") {
+        await program.parseAsync(["node", "prodo", "init", ...argv.slice(2)]);
+      } else if (forced === "normalize") {
+        await program.parseAsync(["node", "prodo", "normalize", ...argv.slice(2)]);
+      } else if (forced === "validate") {
+        await program.parseAsync(["node", "prodo", "validate", ...argv.slice(2)]);
+      } else {
+        await program.parseAsync(["node", "prodo", forced, ...argv.slice(2)]);
+      }
+    } else {
+      await program.parseAsync(argv);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof UserError) {
+      err(error.message);
+      return 1;
+    }
+    const unknown = error as Error;
+    err(unknown.message);
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  runCli().then((code) => {
+    process.exitCode = code;
+  });
+}

package/src/consistency.ts

@@ -0,0 +1,303 @@
+import path from "node:path";
+import { listArtifactTypes, getArtifactDefinition } from "./artifact-registry";
+import { contractIds, parseNormalizedBriefOrThrow } from "./normalized-brief";
+import { createProvider } from "./providers";
+import type { ArtifactDoc, ArtifactType, ContractCoverage, ValidationIssue } from "./types";
+
+type LoadedArtifact = {
+  type: ArtifactType;
+  file: string;
+  doc: ArtifactDoc;
+};
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function readCoverage(frontmatter: Record<string, unknown>): ContractCoverage {
+  const coverage = frontmatter.contract_coverage as Partial<ContractCoverage> | undefined;
+  return {
+    goals: asStringArray(coverage?.goals),
+    core_features: asStringArray(coverage?.core_features),
+    constraints: asStringArray(coverage?.constraints)
+  };
+}
+
+async function checkMissingArtifacts(cwd: string, loadedArtifacts: LoadedArtifact[]): Promise<ValidationIssue[]> {
+  const expectedTypes = await listArtifactTypes(cwd);
+  const present = new Set(loadedArtifacts.map((item) => item.type));
+  const missing = expectedTypes.filter((type) => !present.has(type));
+  if (missing.length === 0) return [];
+  return [
+    {
+      level: "warning",
+      code: "missing_artifacts",
+      check: "schema",
+      message: `Some artifacts are missing from outputs: ${missing.join(", ")}`,
+      suggestion: "Run the corresponding prodo-* commands before final validation."
+    }
+  ];
+}
+
+async function checkContractCoverage(
+  cwd: string,
+  loaded: LoadedArtifact[],
+  normalizedBrief: Record<string, unknown>
+): Promise<ValidationIssue[]> {
+  const issues: ValidationIssue[] = [];
+  const normalized = parseNormalizedBriefOrThrow(normalizedBrief);
+  const expected = contractIds(normalized.contracts);
+
+  for (const artifact of loaded) {
+    const def = await getArtifactDefinition(cwd, artifact.type);
+    const coverage = readCoverage(artifact.doc.frontmatter);
+    for (const key of def.required_contracts) {
+      const missing = expected[key].filter((id) => !coverage[key].includes(id));
+      if (missing.length === 0) continue;
+      issues.push({
+        level: "error",
+        code: "missing_contract_coverage",
+        check: "tag_coverage",
+        artifactType: artifact.type,
+        file: artifact.file,
+        field: `frontmatter.contract_coverage.${key}`,
+        message: `Artifact is missing required contract IDs for ${key}: ${missing.join(", ")}`,
+        suggestion: "Regenerate artifact and include explicit contract tags such as [G1], [F2], [C1]."
+      });
+    }
+  }
+
+  return issues;
+}
+
+function checkUpstreamReferences(loaded: LoadedArtifact[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const filesByName = new Set(loaded.map((item) => path.normalize(item.file)));
+
+  for (const artifact of loaded) {
+    const upstream = artifact.doc.frontmatter.upstream_artifacts;
+    if (!Array.isArray(upstream)) continue;
+
+    for (const rawItem of upstream) {
+      if (typeof rawItem !== "string") continue;
+      const resolved = path.normalize(path.resolve(path.dirname(artifact.file), rawItem));
+      if (!filesByName.has(resolved)) {
+        issues.push({
+          level: "error",
+          code: "broken_upstream_reference",
+          check: "schema",
+          artifactType: artifact.type,
+          file: artifact.file,
+          field: "frontmatter.upstream_artifacts",
+          message: `Referenced upstream artifact not found: ${rawItem}`,
+          suggestion: "Regenerate this artifact or update upstream_artifacts paths to existing outputs."
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+function taggedLinesByContract(body: string): Array<{ contractId: string; line: string }> {
+  const lines = body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  const tagged: Array<{ contractId: string; line: string }> = [];
+  for (const line of lines) {
+    const matches = line.match(/\[([GFC][0-9]+)\]/g) ?? [];
+    for (const match of matches) {
+      tagged.push({ contractId: match.slice(1, -1), line });
+    }
+  }
+  return tagged;
+}
+
+function parseJsonObject<T>(raw: string, fallback: T): T {
+  const trimmed = raw.trim();
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fenced ? fenced[1] : trimmed;
+  try {
+    return JSON.parse(candidate) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function hasEnglishLeak(body: string): boolean {
+  const markers = [" the ", " and ", " with ", " user ", " should ", " must "];
+  const normalized = ` ${body.toLowerCase().replace(/\s+/g, " ")} `;
+  return markers.filter((item) => normalized.includes(item)).length >= 2;
+}
+
+function checkLanguageConsistency(loaded: LoadedArtifact[]): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  const languages = new Set<string>();
+  for (const artifact of loaded) {
+    const lang = String((artifact.doc.frontmatter.language ?? "")).toLowerCase();
+    if (lang) languages.add(lang);
+    if (lang.startsWith("tr") && hasEnglishLeak(artifact.doc.body)) {
+      issues.push({
+        level: "error",
+        code: "language_mixed_content",
+        check: "schema",
+        artifactType: artifact.type,
+        file: artifact.file,
+        message: "Artifact contains mixed language content while target language is Turkish.",
+        suggestion: "Regenerate artifact with strict Turkish output."
+      });
+    }
+  }
+  if (languages.size > 1) {
+    issues.push({
+      level: "error",
+      code: "language_inconsistent_across_artifacts",
+      check: "schema",
+      message: "Artifacts have inconsistent language settings.",
+      suggestion: "Regenerate artifacts so all frontmatter.language values match."
+    });
+  }
+  return issues;
+}
+
+async function checkContractRelevance(
+  loaded: LoadedArtifact[],
+  normalizedBrief: Record<string, unknown>
+): Promise<ValidationIssue[]> {
+  const normalized = parseNormalizedBriefOrThrow(normalizedBrief);
+  const contractMap = new Map<string, string>();
+  for (const item of normalized.contracts.goals) contractMap.set(item.id, item.text);
+  for (const item of normalized.contracts.core_features) contractMap.set(item.id, item.text);
+  for (const item of normalized.contracts.constraints) contractMap.set(item.id, item.text);
+
+  const provider = createProvider();
+  const issues: ValidationIssue[] = [];
+  for (const artifact of loaded) {
+    const taggedLines = taggedLinesByContract(artifact.doc.body);
+    for (const tagged of taggedLines) {
+      const contractText = contractMap.get(tagged.contractId);
+      if (!contractText) {
+        issues.push({
+          level: "error",
+          code: "unknown_contract_tag",
+          check: "contract_relevance",
+          artifactType: artifact.type,
+          file: artifact.file,
+          field: tagged.contractId,
+          message: `Unknown contract tag used: ${tagged.contractId}`,
+          suggestion: "Use only contract IDs that exist in normalized brief contracts."
+        });
+        continue;
+      }
+
+      const response = await provider.generate(
+        "Evaluate if tagged line semantically matches contract text.",
+        {
+          contract_id: tagged.contractId,
+          contract_text: contractText,
+          context_text: tagged.line
+        },
+        {
+          artifactType: "contract_relevance",
+          requiredHeadings: [],
+          requiredContracts: []
+        }
+      );
+
+      const verdict = parseJsonObject<{ relevant?: boolean; score?: number; reason?: string }>(response.body, {});
+      const relevant = Boolean(verdict.relevant);
+      if (!relevant) {
+        issues.push({
+          level: "error",
+          code: "irrelevant_contract_tag_usage",
+          check: "contract_relevance",
+          artifactType: artifact.type,
+          file: artifact.file,
+          field: tagged.contractId,
+          message: `Tag ${tagged.contractId} does not match nearby content semantically.`,
+          suggestion: verdict.reason ?? "Rewrite the tagged sentence so it clearly addresses the referenced contract."
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+async function checkSemanticPairs(loaded: LoadedArtifact[]): Promise<ValidationIssue[]> {
+  const byType = new Map<ArtifactType, LoadedArtifact>();
+  for (const artifact of loaded) byType.set(artifact.type, artifact);
+
+  const pairs: Array<[ArtifactType, ArtifactType]> = [
+    ["prd", "stories"],
+    ["workflow", "techspec"],
+    ["workflow", "wireframe"]
+  ];
+  const provider = createProvider();
+  const issues: ValidationIssue[] = [];
+
+  for (const [leftType, rightType] of pairs) {
+    const left = byType.get(leftType);
+    const right = byType.get(rightType);
+    if (!left || !right) continue;
+
+    const result = await provider.generate(
+      "Compare paired artifacts semantically and return contradictions.",
+      {
+        pair: {
+          left_type: leftType,
+          left_file: left.file,
+          left_coverage: readCoverage(left.doc.frontmatter),
+          left_body: left.doc.body,
+          right_type: rightType,
+          right_file: right.file,
+          right_coverage: readCoverage(right.doc.frontmatter),
+          right_body: right.doc.body
+        }
+      },
+      {
+        artifactType: "semantic_consistency",
+        requiredHeadings: [],
+        requiredContracts: []
+      }
+    );
+
+    const parsed = parseJsonObject<{ issues?: Array<Record<string, unknown>> }>(result.body, { issues: [] });
+    for (const item of parsed.issues ?? []) {
+      issues.push({
+        level: (item.level === "warning" ? "warning" : "error") as "error" | "warning",
+        code: typeof item.code === "string" ? item.code : "semantic_inconsistency",
+        check: "semantic_consistency",
+        file: typeof item.file === "string" ? item.file : left.file,
+        field: typeof item.contract_id === "string" ? item.contract_id : undefined,
+        message:
+          typeof item.message === "string"
+            ? item.message
+            : `Semantic mismatch between ${leftType} and ${rightType}.`,
+        suggestion:
+          typeof item.suggestion === "string"
+            ? item.suggestion
+            : `Align ${leftType} and ${rightType} decisions and regenerate.`
+      });
+    }
+  }
+
+  return issues;
+}
+
+export async function checkConsistency(
+  cwd: string,
+  loadedArtifacts: LoadedArtifact[],
+  normalizedBrief: Record<string, unknown>
+): Promise<ValidationIssue[]> {
+  const baseIssues = [
+    ...(await checkMissingArtifacts(cwd, loadedArtifacts)),
+    ...(await checkContractCoverage(cwd, loadedArtifacts, normalizedBrief)),
+    ...checkUpstreamReferences(loadedArtifacts),
+    ...checkLanguageConsistency(loadedArtifacts)
+  ];
+  const relevanceIssues = await checkContractRelevance(loadedArtifacts, normalizedBrief);
+  const semanticIssues = await checkSemanticPairs(loadedArtifacts);
+  return [...baseIssues, ...relevanceIssues, ...semanticIssues];
+}

package/src/constants.ts

@@ -0,0 +1,72 @@
+import type { ContractCoverage, CoreArtifactType } from "./types";
+
+export const PRODO_DIR = ".prodo";
+export const DEFAULT_STATUS = "draft";
+
+const CORE_OUTPUT_DIR_BY_ARTIFACT: Record<CoreArtifactType, string> = {
+  prd: "prd",
+  workflow: "workflows",
+  wireframe: "wireframes",
+  stories: "stories",
+  techspec: "techspec"
+};
+
+const CORE_REQUIRED_HEADINGS: Record<CoreArtifactType, string[]> = {
+  prd: ["## Problem", "## Goals", "## Scope", "## Requirements"],
+  workflow: [
+    "## Flow Purpose",
+    "## Actors",
+    "## Preconditions",
+    "## Main Flow",
+    "## Edge Cases",
+    "## Postconditions"
+  ],
+  wireframe: [
+    "## Screen Purpose",
+    "## Primary Actor",
+    "## Main Sections",
+    "## Fields/Inputs",
+    "## Actions/Buttons",
+    "## States/Messages",
+    "## Notes"
+  ],
+  stories: ["## User Stories", "## Acceptance Criteria"],
+  techspec: ["## Architecture", "## Data Model", "## APIs", "## Risks"]
+};
+
+const CORE_UPSTREAM_BY_ARTIFACT: Record<CoreArtifactType, CoreArtifactType[]> = {
+  prd: [],
+  workflow: ["prd"],
+  wireframe: ["prd", "workflow"],
+  stories: ["prd"],
+  techspec: ["prd", "stories"]
+};
+
+const CORE_REQUIRED_CONTRACTS_BY_ARTIFACT: Record<
+  CoreArtifactType,
+  Array<keyof ContractCoverage>
+> = {
+  prd: ["goals", "core_features"],
+  workflow: ["core_features"],
+  wireframe: ["core_features"],
+  stories: ["core_features"],
+  techspec: ["core_features", "constraints"]
+};
+
+export function defaultOutputDir(artifactType: string): string {
+  return CORE_OUTPUT_DIR_BY_ARTIFACT[artifactType as CoreArtifactType] ?? `${artifactType}s`;
+}
+
+export function defaultRequiredHeadings(artifactType: string): string[] {
+  return CORE_REQUIRED_HEADINGS[artifactType as CoreArtifactType] ?? ["## Summary", "## Details"];
+}
+
+export function defaultUpstreamByArtifact(artifactType: string): string[] {
+  return CORE_UPSTREAM_BY_ARTIFACT[artifactType as CoreArtifactType] ?? [];
+}
+
+export function defaultRequiredContractsByArtifact(
+  artifactType: string
+): Array<keyof ContractCoverage> {
+  return CORE_REQUIRED_CONTRACTS_BY_ARTIFACT[artifactType as CoreArtifactType] ?? ["core_features"];
+}