@wizdear/atlas-code 0.2.4 → 0.2.6

package/dist/standards.d.ts

@@ -1,18 +1,44 @@
-import type { AgentRole, StandardFileName, VibeConfig } from "./types.js";
-/** Default standards mapping by role */
-export declare const DEFAULT_ROLE_STANDARDS: Record<AgentRole, StandardFileName[]>;
+import type { VibeConfig } from "./types.js";
+/** Parsed frontmatter result. */
+export interface StandardsFrontmatter {
+    description?: string;
+}
+/** Single entry in the standards index. */
+export interface StandardsIndexEntry {
+    filename: string;
+    description: string;
+}
+/** Result of building the standards index. */
+export interface StandardsIndexResult {
+    entries: StandardsIndexEntry[];
+    /** Filenames that had frontmatter auto-added. */
+    autoFixed: string[];
+}
 /**
- * Returns the list of standard filenames that will actually be loaded for the given role (existing ones only).
+ * Parses YAML frontmatter from markdown content.
+ * Extracts the `description` field. Returns empty object if no frontmatter found.
  */
-export declare function getLoadedStandards(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string[]>;
+export declare function parseFrontmatter(content: string): StandardsFrontmatter;
 /**
- * Loads the standard files mapped to a role and returns them as a concatenated string.
- * Returns an empty string if no standard files are found.
+ * Extracts the first `# Heading` from markdown content.
+ * Returns undefined if no heading found.
  */
-export declare function loadStandardsForRole(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string>;
+export declare function extractFirstHeading(content: string): string | undefined;
 /**
- * Formats the loaded standards content as a system prompt section.
- * Returns an empty string if the input is empty.
+ * Generates a YAML frontmatter block with a description field.
  */
-export declare function formatStandardsPrompt(standardsContent: string): string;
+export declare function generateFrontmatter(description: string): string;
+/**
+ * Scans all standards sources, parses frontmatter descriptions,
+ * and returns a list of index entries sorted by filename.
+ *
+ * Description priority: frontmatter description > first # heading > filename (without .md).
+ * Files missing frontmatter are auto-fixed: a frontmatter block is prepended and written back.
+ */
+export declare function buildStandardsIndex(config: VibeConfig, projectRoot: string): Promise<StandardsIndexResult>;
+/**
+ * Formats index entries as a system prompt section.
+ * Returns empty string if no entries.
+ */
+export declare function formatStandardsIndexPrompt(entries: StandardsIndexEntry[], standardsDir?: string): string;
 //# sourceMappingURL=standards.d.ts.map

package/dist/standards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"standards.d.ts","sourceRoot":"","sources":["../src/standards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE,gBAAgB,EAAE,CAqDxE,CAAC;AA6DF;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAKpH;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBpH;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAUtE","sourcesContent":["import { access, readdir, readFile, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, join, resolve } from \"node:path\";\nimport type { AgentRole, StandardFileName, VibeConfig } from \"./types.js\";\n\n/** Default standards mapping by role */\nexport const DEFAULT_ROLE_STANDARDS: Record<AgentRole, StandardFileName[]> = {\n\tplanner: [\".artifact-standards.md\"],\n\tarchitect: [\n\t\t\"architecture-principles.md\",\n\t\t\"tech-stack.md\",\n\t\t\"design-guide.md\",\n\t\t\"api-design.md\",\n\t\t\"security-policy.md\",\n\t\t\".artifact-standards.md\",\n\t],\n\tdeveloper: [\n\t\t\"coding-style.md\",\n\t\t\"coding-conventions.md\",\n\t\t\"tech-stack.md\",\n\t\t\"api-design.md\",\n\t\t\"documentation.md\",\n\t\t\"dependency-policy.md\",\n\t\t\"performance-guidelines.md\",\n\t\t\"accessibility.md\",\n\t\t\"observability.md\",\n\t\t\"logging.md\",\n\t],\n\ttester: [\"testing-standards.md\", \"coding-conventions.md\", \"performance-guidelines.md\", \".artifact-standards.md\"],\n\treviewer: [\n\t\t\"coding-style.md\",\n\t\t\"coding-conventions.md\",\n\t\t\"architecture-principles.md\",\n\t\t\"api-design.md\",\n\t\t\"testing-standards.md\",\n\t\t\"documentation.md\",\n\t\t\"security-policy.md\",\n\t\t\"dependency-policy.md\",\n\t\t\"performance-guidelines.md\",\n\t\t\"accessibility.md\",\n\t\t\"observability.md\",\n\t\t\"logging.md\",\n\t\t\".artifact-standards.md\",\n\t],\n\tcicd: [\"git-workflow.md\"],\n\tanalyzer: [\"architecture-principles.md\", \"tech-stack.md\", \".artifact-standards.md\"],\n\tdiagnostician: [\"coding-conventions.md\", \"observability.md\", \"logging.md\", \".artifact-standards.md\"],\n\tdiscovery: [\".artifact-standards.md\"],\n\tprojectAnalyzer: [\".artifact-standards.md\"],\n\tdocumenter: [\"documentation.md\", \".artifact-standards.md\"],\n\tstandardsEnricher: [],\n\tsystemArchitect: [\n\t\t\"architecture-principles.md\",\n\t\t\"tech-stack.md\",\n\t\t\"design-guide.md\",\n\t\t\"api-design.md\",\n\t\t\"security-policy.md\",\n\t\t\".artifact-standards.md\",\n\t],\n};\n\n/** Checks whether a file exists. */\nasync function fileExists(path: string): Promise<boolean> {\n\ttry {\n\t\tawait access(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Resolves a path to an absolute path relative to projectRoot. */\nfunction resolvePath(source: string, projectRoot: string): string {\n\tif (isAbsolute(source)) {\n\t\treturn source;\n\t}\n\treturn resolve(projectRoot, source);\n}\n\n/**\n * Traverses all source paths and returns a Map<filename, absolutePath> of discovered .md files.\n * When the same filename exists in multiple sources, the later source takes precedence.\n */\nasync function resolveStandardFiles(sources: string[], projectRoot: string): Promise<Map<string, string>> {\n\tconst result = new Map<string, string>();\n\n\tfor (const source of sources) {\n\t\tconst absPath = resolvePath(source, projectRoot);\n\t\tif (!(await fileExists(absPath))) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst info = await stat(absPath);\n\t\tif (info.isDirectory()) {\n\t\t\tconst entries = await readdir(absPath);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (entry.endsWith(\".md\")) {\n\t\t\t\t\tresult.set(entry, join(absPath, entry));\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (info.isFile()) {\n\t\t\tresult.set(basename(absPath), absPath);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Determines the list of standard filenames mapped to a role.\n * Uses config.standards.roleMapping if the role exists there; otherwise uses DEFAULT_ROLE_STANDARDS.\n */\nfunction getRoleMappedFiles(role: AgentRole, config: VibeConfig): string[] {\n\tconst customMapping = config.standards.roleMapping;\n\tif (customMapping && role in customMapping) {\n\t\treturn customMapping[role] ?? DEFAULT_ROLE_STANDARDS[role];\n\t}\n\treturn DEFAULT_ROLE_STANDARDS[role];\n}\n\n/**\n * Returns the list of standard filenames that will actually be loaded for the given role (existing ones only).\n */\nexport async function getLoadedStandards(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string[]> {\n\tconst availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst mappedFiles = getRoleMappedFiles(role, config);\n\n\treturn mappedFiles.filter((fileName) => availableFiles.has(fileName));\n}\n\n/**\n * Loads the standard files mapped to a role and returns them as a concatenated string.\n * Returns an empty string if no standard files are found.\n */\nexport async function loadStandardsForRole(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string> {\n\tconst availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst mappedFiles = getRoleMappedFiles(role, config);\n\n\tconst contents: string[] = [];\n\tfor (const fileName of mappedFiles) {\n\t\tconst filePath = availableFiles.get(fileName);\n\t\tif (filePath) {\n\t\t\tconst content = await readFile(filePath, \"utf-8\");\n\t\t\tcontents.push(content.trim());\n\t\t}\n\t}\n\n\tif (contents.length === 0) {\n\t\treturn \"\";\n\t}\n\n\treturn contents.join(\"\\n\\n---\\n\\n\");\n}\n\n/**\n * Formats the loaded standards content as a system prompt section.\n * Returns an empty string if the input is empty.\n */\nexport function formatStandardsPrompt(standardsContent: string): string {\n\tif (!standardsContent) {\n\t\treturn \"\";\n\t}\n\n\treturn `## Organization Standards\n\nYou MUST follow these standards:\n\n${standardsContent}`;\n}\n"]}
+{"version":3,"file":"standards.d.ts","sourceRoot":"","sources":["../src/standards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;CACpB;AAqDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA+BhH;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBxG","sourcesContent":["import { access, readdir, readFile, stat, writeFile } from \"node:fs/promises\";\nimport { basename, isAbsolute, join, resolve } from \"node:path\";\nimport type { VibeConfig } from \"./types.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Parsed frontmatter result. */\nexport interface StandardsFrontmatter {\n\tdescription?: string;\n}\n\n/** Single entry in the standards index. */\nexport interface StandardsIndexEntry {\n\tfilename: string;\n\tdescription: string;\n}\n\n/** Result of building the standards index. */\nexport interface StandardsIndexResult {\n\tentries: StandardsIndexEntry[];\n\t/** Filenames that had frontmatter auto-added. */\n\tautoFixed: string[];\n}\n\n// ─── Internal Helpers ────────────────────────────────────────────────────────\n\n/** Checks whether a file exists. */\nasync function fileExists(path: string): Promise<boolean> {\n\ttry {\n\t\tawait access(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Resolves a path to an absolute path relative to projectRoot. */\nfunction resolvePath(source: string, projectRoot: string): string {\n\tif (isAbsolute(source)) {\n\t\treturn source;\n\t}\n\treturn resolve(projectRoot, source);\n}\n\n/**\n * Traverses all source paths and returns a Map<filename, absolutePath> of discovered .md files.\n * When the same filename exists in multiple sources, the later source takes precedence.\n */\nasync function resolveStandardFiles(sources: string[], projectRoot: string): Promise<Map<string, string>> {\n\tconst result = new Map<string, string>();\n\n\tfor (const source of sources) {\n\t\tconst absPath = resolvePath(source, projectRoot);\n\t\tif (!(await fileExists(absPath))) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst info = await stat(absPath);\n\t\tif (info.isDirectory()) {\n\t\t\tconst entries = await readdir(absPath);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (entry.endsWith(\".md\")) {\n\t\t\t\t\tresult.set(entry, join(absPath, entry));\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (info.isFile()) {\n\t\t\tresult.set(basename(absPath), absPath);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Parses YAML frontmatter from markdown content.\n * Extracts the `description` field. Returns empty object if no frontmatter found.\n */\nexport function parseFrontmatter(content: string): StandardsFrontmatter {\n\tif (!content.startsWith(\"---\")) {\n\t\treturn {};\n\t}\n\n\tconst endIndex = content.indexOf(\"\\n---\", 3);\n\tif (endIndex === -1) {\n\t\treturn {};\n\t}\n\n\tconst frontmatterBlock = content.slice(3, endIndex);\n\tconst descMatch = frontmatterBlock.match(/^\\s*description\\s*:\\s*(.+)$/m);\n\tif (!descMatch) {\n\t\treturn {};\n\t}\n\n\treturn { description: descMatch[1].trim() };\n}\n\n/**\n * Extracts the first `# Heading` from markdown content.\n * Returns undefined if no heading found.\n */\nexport function extractFirstHeading(content: string): string | undefined {\n\tconst match = content.match(/^#\\s+(.+)$/m);\n\treturn match ? match[1].trim() : undefined;\n}\n\n/**\n * Generates a YAML frontmatter block with a description field.\n */\nexport function generateFrontmatter(description: string): string {\n\treturn `---\\ndescription: ${description}\\n---\\n`;\n}\n\n/**\n * Scans all standards sources, parses frontmatter descriptions,\n * and returns a list of index entries sorted by filename.\n *\n * Description priority: frontmatter description > first # heading > filename (without .md).\n * Files missing frontmatter are auto-fixed: a frontmatter block is prepended and written back.\n */\nexport async function buildStandardsIndex(config: VibeConfig, projectRoot: string): Promise<StandardsIndexResult> {\n\tconst files = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst entries: StandardsIndexEntry[] = [];\n\tconst autoFixed: string[] = [];\n\n\tfor (const [filename, filePath] of files) {\n\t\tconst content = await readFile(filePath, \"utf-8\");\n\t\tconst frontmatter = parseFrontmatter(content);\n\n\t\tlet description: string;\n\t\tif (frontmatter.description) {\n\t\t\tdescription = frontmatter.description;\n\t\t} else {\n\t\t\tconst heading = extractFirstHeading(content);\n\t\t\tdescription = heading ?? filename.replace(/\\.md$/, \"\");\n\n\t\t\t// Auto-prepend frontmatter and write back\n\t\t\tconst newContent = generateFrontmatter(description) + content;\n\t\t\ttry {\n\t\t\t\tawait writeFile(filePath, newContent, \"utf-8\");\n\t\t\t\tautoFixed.push(filename);\n\t\t\t} catch {\n\t\t\t\t// Graceful failure: skip write, continue with derived description\n\t\t\t}\n\t\t}\n\n\t\tentries.push({ filename, description });\n\t}\n\n\tentries.sort((a, b) => a.filename.localeCompare(b.filename));\n\treturn { entries, autoFixed };\n}\n\n/**\n * Formats index entries as a system prompt section.\n * Returns empty string if no entries.\n */\nexport function formatStandardsIndexPrompt(entries: StandardsIndexEntry[], standardsDir?: string): string {\n\tif (entries.length === 0) {\n\t\treturn \"\";\n\t}\n\n\tconst dir = standardsDir ?? \".vibe/standards\";\n\tconst rows = entries.map((e) => `| \\`${e.filename}\\` | ${e.description} |`).join(\"\\n\");\n\n\treturn `## Organization Standards\n\nThe following standards are available in \\`${dir}/\\`.\nRead the ones relevant to your role and current task before proceeding.\n\n| File | Description |\n|------|-------------|\n${rows}`;\n}\n"]}

package/dist/standards.js

@@ -1,60 +1,6 @@
-import { access, readdir, readFile, stat } from "node:fs/promises";
+import { access, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, isAbsolute, join, resolve } from "node:path";
-/** Default standards mapping by role */
-export const DEFAULT_ROLE_STANDARDS = {
-    planner: [".artifact-standards.md"],
-    architect: [
-        "architecture-principles.md",
-        "tech-stack.md",
-        "design-guide.md",
-        "api-design.md",
-        "security-policy.md",
-        ".artifact-standards.md",
-    ],
-    developer: [
-        "coding-style.md",
-        "coding-conventions.md",
-        "tech-stack.md",
-        "api-design.md",
-        "documentation.md",
-        "dependency-policy.md",
-        "performance-guidelines.md",
-        "accessibility.md",
-        "observability.md",
-        "logging.md",
-    ],
-    tester: ["testing-standards.md", "coding-conventions.md", "performance-guidelines.md", ".artifact-standards.md"],
-    reviewer: [
-        "coding-style.md",
-        "coding-conventions.md",
-        "architecture-principles.md",
-        "api-design.md",
-        "testing-standards.md",
-        "documentation.md",
-        "security-policy.md",
-        "dependency-policy.md",
-        "performance-guidelines.md",
-        "accessibility.md",
-        "observability.md",
-        "logging.md",
-        ".artifact-standards.md",
-    ],
-    cicd: ["git-workflow.md"],
-    analyzer: ["architecture-principles.md", "tech-stack.md", ".artifact-standards.md"],
-    diagnostician: ["coding-conventions.md", "observability.md", "logging.md", ".artifact-standards.md"],
-    discovery: [".artifact-standards.md"],
-    projectAnalyzer: [".artifact-standards.md"],
-    documenter: ["documentation.md", ".artifact-standards.md"],
-    standardsEnricher: [],
-    systemArchitect: [
-        "architecture-principles.md",
-        "tech-stack.md",
-        "design-guide.md",
-        "api-design.md",
-        "security-policy.md",
-        ".artifact-standards.md",
-    ],
-};
+// ─── Internal Helpers ────────────────────────────────────────────────────────
 /** Checks whether a file exists. */
 async function fileExists(path) {
     try {
@@ -98,57 +44,93 @@ async function resolveStandardFiles(sources, projectRoot) {
     }
     return result;
 }
+// ─── Public API ──────────────────────────────────────────────────────────────
 /**
- * Determines the list of standard filenames mapped to a role.
- * Uses config.standards.roleMapping if the role exists there; otherwise uses DEFAULT_ROLE_STANDARDS.
+ * Parses YAML frontmatter from markdown content.
+ * Extracts the `description` field. Returns empty object if no frontmatter found.
  */
-function getRoleMappedFiles(role, config) {
-    const customMapping = config.standards.roleMapping;
-    if (customMapping && role in customMapping) {
-        return customMapping[role] ?? DEFAULT_ROLE_STANDARDS[role];
+export function parseFrontmatter(content) {
+    if (!content.startsWith("---")) {
+        return {};
     }
-    return DEFAULT_ROLE_STANDARDS[role];
+    const endIndex = content.indexOf("\n---", 3);
+    if (endIndex === -1) {
+        return {};
+    }
+    const frontmatterBlock = content.slice(3, endIndex);
+    const descMatch = frontmatterBlock.match(/^\s*description\s*:\s*(.+)$/m);
+    if (!descMatch) {
+        return {};
+    }
+    return { description: descMatch[1].trim() };
+}
+/**
+ * Extracts the first `# Heading` from markdown content.
+ * Returns undefined if no heading found.
+ */
+export function extractFirstHeading(content) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : undefined;
 }
 /**
- * Returns the list of standard filenames that will actually be loaded for the given role (existing ones only).
+ * Generates a YAML frontmatter block with a description field.
  */
-export async function getLoadedStandards(role, config, projectRoot) {
-    const availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);
-    const mappedFiles = getRoleMappedFiles(role, config);
-    return mappedFiles.filter((fileName) => availableFiles.has(fileName));
+export function generateFrontmatter(description) {
+    return `---\ndescription: ${description}\n---\n`;
 }
 /**
- * Loads the standard files mapped to a role and returns them as a concatenated string.
- * Returns an empty string if no standard files are found.
+ * Scans all standards sources, parses frontmatter descriptions,
+ * and returns a list of index entries sorted by filename.
+ *
+ * Description priority: frontmatter description > first # heading > filename (without .md).
+ * Files missing frontmatter are auto-fixed: a frontmatter block is prepended and written back.
  */
-export async function loadStandardsForRole(role, config, projectRoot) {
-    const availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);
-    const mappedFiles = getRoleMappedFiles(role, config);
-    const contents = [];
-    for (const fileName of mappedFiles) {
-        const filePath = availableFiles.get(fileName);
-        if (filePath) {
-            const content = await readFile(filePath, "utf-8");
-            contents.push(content.trim());
+export async function buildStandardsIndex(config, projectRoot) {
+    const files = await resolveStandardFiles(config.standards.sources, projectRoot);
+    const entries = [];
+    const autoFixed = [];
+    for (const [filename, filePath] of files) {
+        const content = await readFile(filePath, "utf-8");
+        const frontmatter = parseFrontmatter(content);
+        let description;
+        if (frontmatter.description) {
+            description = frontmatter.description;
         }
+        else {
+            const heading = extractFirstHeading(content);
+            description = heading ?? filename.replace(/\.md$/, "");
+            // Auto-prepend frontmatter and write back
+            const newContent = generateFrontmatter(description) + content;
+            try {
+                await writeFile(filePath, newContent, "utf-8");
+                autoFixed.push(filename);
+            }
+            catch {
+                // Graceful failure: skip write, continue with derived description
+            }
+        }
+        entries.push({ filename, description });
     }
-    if (contents.length === 0) {
-        return "";
-    }
-    return contents.join("\n\n---\n\n");
+    entries.sort((a, b) => a.filename.localeCompare(b.filename));
+    return { entries, autoFixed };
 }
 /**
- * Formats the loaded standards content as a system prompt section.
- * Returns an empty string if the input is empty.
+ * Formats index entries as a system prompt section.
+ * Returns empty string if no entries.
  */
-export function formatStandardsPrompt(standardsContent) {
-    if (!standardsContent) {
+export function formatStandardsIndexPrompt(entries, standardsDir) {
+    if (entries.length === 0) {
         return "";
     }
+    const dir = standardsDir ?? ".vibe/standards";
+    const rows = entries.map((e) => `| \`${e.filename}\` | ${e.description} |`).join("\n");
     return `## Organization Standards
 
-You MUST follow these standards:
+The following standards are available in \`${dir}/\`.
+Read the ones relevant to your role and current task before proceeding.
 
-${standardsContent}`;
+| File | Description |
+|------|-------------|
+${rows}`;
 }
 //# sourceMappingURL=standards.js.map

package/dist/standards.js.map

@@ -1 +1 @@
-{"version":3,"file":"standards.js","sourceRoot":"","sources":["../src/standards.ts"],"names":[],"mappings":"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","sourcesContent":["import { access, readdir, readFile, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, join, resolve } from \"node:path\";\nimport type { AgentRole, StandardFileName, VibeConfig } from \"./types.js\";\n\n/** Default standards mapping by role */\nexport const DEFAULT_ROLE_STANDARDS: Record<AgentRole, StandardFileName[]> = {\n\tplanner: [\".artifact-standards.md\"],\n\tarchitect: [\n\t\t\"architecture-principles.md\",\n\t\t\"tech-stack.md\",\n\t\t\"design-guide.md\",\n\t\t\"api-design.md\",\n\t\t\"security-policy.md\",\n\t\t\".artifact-standards.md\",\n\t],\n\tdeveloper: [\n\t\t\"coding-style.md\",\n\t\t\"coding-conventions.md\",\n\t\t\"tech-stack.md\",\n\t\t\"api-design.md\",\n\t\t\"documentation.md\",\n\t\t\"dependency-policy.md\",\n\t\t\"performance-guidelines.md\",\n\t\t\"accessibility.md\",\n\t\t\"observability.md\",\n\t\t\"logging.md\",\n\t],\n\ttester: [\"testing-standards.md\", \"coding-conventions.md\", \"performance-guidelines.md\", \".artifact-standards.md\"],\n\treviewer: [\n\t\t\"coding-style.md\",\n\t\t\"coding-conventions.md\",\n\t\t\"architecture-principles.md\",\n\t\t\"api-design.md\",\n\t\t\"testing-standards.md\",\n\t\t\"documentation.md\",\n\t\t\"security-policy.md\",\n\t\t\"dependency-policy.md\",\n\t\t\"performance-guidelines.md\",\n\t\t\"accessibility.md\",\n\t\t\"observability.md\",\n\t\t\"logging.md\",\n\t\t\".artifact-standards.md\",\n\t],\n\tcicd: [\"git-workflow.md\"],\n\tanalyzer: [\"architecture-principles.md\", \"tech-stack.md\", \".artifact-standards.md\"],\n\tdiagnostician: [\"coding-conventions.md\", \"observability.md\", \"logging.md\", \".artifact-standards.md\"],\n\tdiscovery: [\".artifact-standards.md\"],\n\tprojectAnalyzer: [\".artifact-standards.md\"],\n\tdocumenter: [\"documentation.md\", \".artifact-standards.md\"],\n\tstandardsEnricher: [],\n\tsystemArchitect: [\n\t\t\"architecture-principles.md\",\n\t\t\"tech-stack.md\",\n\t\t\"design-guide.md\",\n\t\t\"api-design.md\",\n\t\t\"security-policy.md\",\n\t\t\".artifact-standards.md\",\n\t],\n};\n\n/** Checks whether a file exists. */\nasync function fileExists(path: string): Promise<boolean> {\n\ttry {\n\t\tawait access(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Resolves a path to an absolute path relative to projectRoot. */\nfunction resolvePath(source: string, projectRoot: string): string {\n\tif (isAbsolute(source)) {\n\t\treturn source;\n\t}\n\treturn resolve(projectRoot, source);\n}\n\n/**\n * Traverses all source paths and returns a Map<filename, absolutePath> of discovered .md files.\n * When the same filename exists in multiple sources, the later source takes precedence.\n */\nasync function resolveStandardFiles(sources: string[], projectRoot: string): Promise<Map<string, string>> {\n\tconst result = new Map<string, string>();\n\n\tfor (const source of sources) {\n\t\tconst absPath = resolvePath(source, projectRoot);\n\t\tif (!(await fileExists(absPath))) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst info = await stat(absPath);\n\t\tif (info.isDirectory()) {\n\t\t\tconst entries = await readdir(absPath);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (entry.endsWith(\".md\")) {\n\t\t\t\t\tresult.set(entry, join(absPath, entry));\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (info.isFile()) {\n\t\t\tresult.set(basename(absPath), absPath);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Determines the list of standard filenames mapped to a role.\n * Uses config.standards.roleMapping if the role exists there; otherwise uses DEFAULT_ROLE_STANDARDS.\n */\nfunction getRoleMappedFiles(role: AgentRole, config: VibeConfig): string[] {\n\tconst customMapping = config.standards.roleMapping;\n\tif (customMapping && role in customMapping) {\n\t\treturn customMapping[role] ?? DEFAULT_ROLE_STANDARDS[role];\n\t}\n\treturn DEFAULT_ROLE_STANDARDS[role];\n}\n\n/**\n * Returns the list of standard filenames that will actually be loaded for the given role (existing ones only).\n */\nexport async function getLoadedStandards(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string[]> {\n\tconst availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst mappedFiles = getRoleMappedFiles(role, config);\n\n\treturn mappedFiles.filter((fileName) => availableFiles.has(fileName));\n}\n\n/**\n * Loads the standard files mapped to a role and returns them as a concatenated string.\n * Returns an empty string if no standard files are found.\n */\nexport async function loadStandardsForRole(role: AgentRole, config: VibeConfig, projectRoot: string): Promise<string> {\n\tconst availableFiles = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst mappedFiles = getRoleMappedFiles(role, config);\n\n\tconst contents: string[] = [];\n\tfor (const fileName of mappedFiles) {\n\t\tconst filePath = availableFiles.get(fileName);\n\t\tif (filePath) {\n\t\t\tconst content = await readFile(filePath, \"utf-8\");\n\t\t\tcontents.push(content.trim());\n\t\t}\n\t}\n\n\tif (contents.length === 0) {\n\t\treturn \"\";\n\t}\n\n\treturn contents.join(\"\\n\\n---\\n\\n\");\n}\n\n/**\n * Formats the loaded standards content as a system prompt section.\n * Returns an empty string if the input is empty.\n */\nexport function formatStandardsPrompt(standardsContent: string): string {\n\tif (!standardsContent) {\n\t\treturn \"\";\n\t}\n\n\treturn `## Organization Standards\n\nYou MUST follow these standards:\n\n${standardsContent}`;\n}\n"]}
+{"version":3,"file":"standards.js","sourceRoot":"","sources":["../src/standards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBhE,sMAAgF;AAEhF,oCAAoC;AACpC,KAAK,UAAU,UAAU,CAAC,IAAY,EAAoB;IACzD,IAAI,CAAC;QACJ,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AAAA,CACD;AAED,mEAAmE;AACnE,SAAS,WAAW,CAAC,MAAc,EAAE,WAAmB,EAAU;IACjE,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,OAAO,MAAM,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAAA,CACpC;AAED;;;GAGG;AACH,KAAK,UAAU,oBAAoB,CAAC,OAAiB,EAAE,WAAmB,EAAgC;IACzG,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEzC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACjD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YAClC,SAAS;QACV,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;YACvC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;gBACzC,CAAC;YACF,CAAC;QACF,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1B,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AAAA,CACd;AAED,kNAAgF;AAEhF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAwB;IACvE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC7C,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACzE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AAAA,CAC5C;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe,EAAsB;IACxE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC3C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CAC3C;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB,EAAU;IAChE,OAAO,qBAAqB,WAAW,SAAS,CAAC;AAAA,CACjD;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAkB,EAAE,WAAmB,EAAiC;IACjH,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAChF,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,WAAW,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,WAAmB,CAAC;QACxB,IAAI,WAAW,CAAC,WAAW,EAAE,CAAC;YAC7B,WAAW,GAAG,WAAW,CAAC,WAAW,CAAC;QACvC,CAAC;aAAM,CAAC;YACP,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC7C,WAAW,GAAG,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAEvD,0CAA0C;YAC1C,MAAM,UAAU,GAAG,mBAAmB,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;YAC9D,IAAI,CAAC;gBACJ,MAAM,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;gBAC/C,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC1B,CAAC;YAAC,MAAM,CAAC;gBACR,kEAAkE;YACnE,CAAC;QACF,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAAA,CAC9B;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAA8B,EAAE,YAAqB,EAAU;IACzG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACX,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,IAAI,iBAAiB,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,QAAQ,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEvF,OAAO;;6CAEqC,GAAG;;;;;EAK9C,IAAI,EAAE,CAAC;AAAA,CACR","sourcesContent":["import { access, readdir, readFile, stat, writeFile } from \"node:fs/promises\";\nimport { basename, isAbsolute, join, resolve } from \"node:path\";\nimport type { VibeConfig } from \"./types.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Parsed frontmatter result. */\nexport interface StandardsFrontmatter {\n\tdescription?: string;\n}\n\n/** Single entry in the standards index. */\nexport interface StandardsIndexEntry {\n\tfilename: string;\n\tdescription: string;\n}\n\n/** Result of building the standards index. */\nexport interface StandardsIndexResult {\n\tentries: StandardsIndexEntry[];\n\t/** Filenames that had frontmatter auto-added. */\n\tautoFixed: string[];\n}\n\n// ─── Internal Helpers ────────────────────────────────────────────────────────\n\n/** Checks whether a file exists. */\nasync function fileExists(path: string): Promise<boolean> {\n\ttry {\n\t\tawait access(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** Resolves a path to an absolute path relative to projectRoot. */\nfunction resolvePath(source: string, projectRoot: string): string {\n\tif (isAbsolute(source)) {\n\t\treturn source;\n\t}\n\treturn resolve(projectRoot, source);\n}\n\n/**\n * Traverses all source paths and returns a Map<filename, absolutePath> of discovered .md files.\n * When the same filename exists in multiple sources, the later source takes precedence.\n */\nasync function resolveStandardFiles(sources: string[], projectRoot: string): Promise<Map<string, string>> {\n\tconst result = new Map<string, string>();\n\n\tfor (const source of sources) {\n\t\tconst absPath = resolvePath(source, projectRoot);\n\t\tif (!(await fileExists(absPath))) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst info = await stat(absPath);\n\t\tif (info.isDirectory()) {\n\t\t\tconst entries = await readdir(absPath);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (entry.endsWith(\".md\")) {\n\t\t\t\t\tresult.set(entry, join(absPath, entry));\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (info.isFile()) {\n\t\t\tresult.set(basename(absPath), absPath);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Parses YAML frontmatter from markdown content.\n * Extracts the `description` field. Returns empty object if no frontmatter found.\n */\nexport function parseFrontmatter(content: string): StandardsFrontmatter {\n\tif (!content.startsWith(\"---\")) {\n\t\treturn {};\n\t}\n\n\tconst endIndex = content.indexOf(\"\\n---\", 3);\n\tif (endIndex === -1) {\n\t\treturn {};\n\t}\n\n\tconst frontmatterBlock = content.slice(3, endIndex);\n\tconst descMatch = frontmatterBlock.match(/^\\s*description\\s*:\\s*(.+)$/m);\n\tif (!descMatch) {\n\t\treturn {};\n\t}\n\n\treturn { description: descMatch[1].trim() };\n}\n\n/**\n * Extracts the first `# Heading` from markdown content.\n * Returns undefined if no heading found.\n */\nexport function extractFirstHeading(content: string): string | undefined {\n\tconst match = content.match(/^#\\s+(.+)$/m);\n\treturn match ? match[1].trim() : undefined;\n}\n\n/**\n * Generates a YAML frontmatter block with a description field.\n */\nexport function generateFrontmatter(description: string): string {\n\treturn `---\\ndescription: ${description}\\n---\\n`;\n}\n\n/**\n * Scans all standards sources, parses frontmatter descriptions,\n * and returns a list of index entries sorted by filename.\n *\n * Description priority: frontmatter description > first # heading > filename (without .md).\n * Files missing frontmatter are auto-fixed: a frontmatter block is prepended and written back.\n */\nexport async function buildStandardsIndex(config: VibeConfig, projectRoot: string): Promise<StandardsIndexResult> {\n\tconst files = await resolveStandardFiles(config.standards.sources, projectRoot);\n\tconst entries: StandardsIndexEntry[] = [];\n\tconst autoFixed: string[] = [];\n\n\tfor (const [filename, filePath] of files) {\n\t\tconst content = await readFile(filePath, \"utf-8\");\n\t\tconst frontmatter = parseFrontmatter(content);\n\n\t\tlet description: string;\n\t\tif (frontmatter.description) {\n\t\t\tdescription = frontmatter.description;\n\t\t} else {\n\t\t\tconst heading = extractFirstHeading(content);\n\t\t\tdescription = heading ?? filename.replace(/\\.md$/, \"\");\n\n\t\t\t// Auto-prepend frontmatter and write back\n\t\t\tconst newContent = generateFrontmatter(description) + content;\n\t\t\ttry {\n\t\t\t\tawait writeFile(filePath, newContent, \"utf-8\");\n\t\t\t\tautoFixed.push(filename);\n\t\t\t} catch {\n\t\t\t\t// Graceful failure: skip write, continue with derived description\n\t\t\t}\n\t\t}\n\n\t\tentries.push({ filename, description });\n\t}\n\n\tentries.sort((a, b) => a.filename.localeCompare(b.filename));\n\treturn { entries, autoFixed };\n}\n\n/**\n * Formats index entries as a system prompt section.\n * Returns empty string if no entries.\n */\nexport function formatStandardsIndexPrompt(entries: StandardsIndexEntry[], standardsDir?: string): string {\n\tif (entries.length === 0) {\n\t\treturn \"\";\n\t}\n\n\tconst dir = standardsDir ?? \".vibe/standards\";\n\tconst rows = entries.map((e) => `| \\`${e.filename}\\` | ${e.description} |`).join(\"\\n\");\n\n\treturn `## Organization Standards\n\nThe following standards are available in \\`${dir}/\\`.\nRead the ones relevant to your role and current task before proceeding.\n\n| File | Description |\n|------|-------------|\n${rows}`;\n}\n"]}

package/dist/step-executor.d.ts

@@ -1,8 +1,10 @@
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { StepContext, StepExecutor, StepUsage } from "./pipeline.js";
-import type { AgentRole, PipelineStep, TestingConfig } from "./types.js";
+import type { AgentRole, CiCheck, PipelineStep, TestingConfig } from "./types.js";
 /** Determines whether the role is readonly (cannot write files via tools). */
 export declare function isReadonlyRole(role: AgentRole): boolean;
+/** Roles that receive system-design.md as additional input context. */
+export declare const SYSTEM_DESIGN_ROLES: ReadonlySet<AgentRole>;
 /**
  * Aggregates token usage from all assistant messages in a conversation.
  * Returns undefined if no assistant messages with usage data are found.
@@ -24,10 +26,21 @@ export declare function loadInputArtifacts(inputs: string[], featureId: string,
  * 3. Return the entire response if it's a single output
  */
 export declare function extractArtifactContent(responseText: string, artifactName: string, isSingleOutput?: boolean): string | null;
+/** Result of lightweight test config detection from project files. */
+export interface DetectedTestConfig {
+    testCommand?: string;
+    ciChecks: CiCheck[];
+}
+/**
+ * Detects test command and CI checks from project files when config.testing is empty.
+ * This is a fast file-existence check — NOT a full project-analyze re-run.
+ * Used for new projects where project-analyze ran before the project scaffold existed.
+ */
+export declare function detectTestConfig(projectRoot: string): Promise<DetectedTestConfig>;
 /**
  * Builds the prompt to send to the agent based on the step's agent role and action.
  */
-export declare function buildActionPrompt(step: PipelineStep, featureId: string, inputContent: string, artifactDir: string, availableSkills?: string, baseBranch?: string, testingConfig?: TestingConfig, projectRoot?: string): string;
+export declare function buildActionPrompt(step: PipelineStep, featureId: string, inputContent: string, artifactDir: string, baseBranch?: string, testingConfig?: TestingConfig, projectRoot?: string): string;
 /**
  * Default StepExecutor implementation.
  * Creates a role-specific agent, passes input artifacts as context,

package/dist/step-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAgB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAcvF,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEvD;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,SAAS,CA8B9E;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBnH;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC7B,MAAM,GAAG,IAAI,CA6Bf;AAwGD;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,GAClB,MAAM,CA4FR;AAsDD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAgHjC,CAAC","sourcesContent":["import type { AgentMessage } from \"@mariozechner/pi-agent-core\";\nimport { createRoleAgent, filterSerializableMessages, runAgentWithHistory } from \"./agent-factory.js\";\nimport { createModuleLogger, noopLogger } from \"./logger.js\";\nimport type { StepContext, StepExecutor, StepUsage } from \"./pipeline.js\";\nimport { getSystemPromptForRole } from \"./roles/index.js\";\nimport type { AgentRole, ArtifactName, PipelineStep, TestingConfig } from \"./types.js\";\n\n// ─── Readonly Role Detection ─────────────────────────────────────────────────\n\n/** Roles that cannot write files via tools. Artifacts are extracted from the response and saved to the store. */\nconst READONLY_ROLES: ReadonlySet<AgentRole> = new Set<AgentRole>([\n\t\"planner\",\n\t\"analyzer\",\n\t\"reviewer\",\n\t\"diagnostician\",\n\t\"discovery\",\n\t\"projectAnalyzer\",\n]);\n\n/** Determines whether the role is readonly (cannot write files via tools). */\nexport function isReadonlyRole(role: AgentRole): boolean {\n\treturn READONLY_ROLES.has(role);\n}\n\n// ─── Usage Aggregation ───────────────────────────────────────────────────────\n\n/**\n * Aggregates token usage from all assistant messages in a conversation.\n * Returns undefined if no assistant messages with usage data are found.\n */\nexport function aggregateUsage(messages: AgentMessage[]): StepUsage | undefined {\n\tlet input = 0;\n\tlet output = 0;\n\tlet cacheRead = 0;\n\tlet cacheWrite = 0;\n\tlet totalTokens = 0;\n\tlet cost = 0;\n\tlet found = false;\n\n\tfor (const msg of messages) {\n\t\tif (msg.role === \"assistant\" && \"usage\" in msg && msg.usage) {\n\t\t\tconst u = msg.usage as {\n\t\t\t\tinput: number;\n\t\t\t\toutput: number;\n\t\t\t\tcacheRead: number;\n\t\t\t\tcacheWrite: number;\n\t\t\t\ttotalTokens: number;\n\t\t\t\tcost: { total: number };\n\t\t\t};\n\t\t\tfound = true;\n\t\t\tinput += u.input;\n\t\t\toutput += u.output;\n\t\t\tcacheRead += u.cacheRead;\n\t\t\tcacheWrite += u.cacheWrite;\n\t\t\ttotalTokens += u.totalTokens;\n\t\t\tcost += u.cost.total;\n\t\t}\n\t}\n\n\treturn found ? { input, output, cacheRead, cacheWrite, totalTokens, cost } : undefined;\n}\n\n// ─── Input Artifact Loader ───────────────────────────────────────────────────\n\n/**\n * Reads the artifact files specified in step.inputs from the store\n * and combines them into a single context string.\n * Non-existent files are skipped.\n */\nexport async function loadInputArtifacts(inputs: string[], featureId: string, context: StepContext): Promise<string> {\n\tif (inputs.length === 0) {\n\t\treturn \"\";\n\t}\n\n\tconst sections: string[] = [];\n\n\tfor (const input of inputs) {\n\t\tconst hasFile = await context.store.hasArtifact(featureId, input as ArtifactName);\n\t\tif (!hasFile) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst content = await context.store.readArtifact(featureId, input as ArtifactName);\n\t\tsections.push(`## Input: ${input}\\n\\n${content}`);\n\t}\n\n\treturn sections.join(\"\\n\\n---\\n\\n\");\n}\n\n// ─── Artifact Extraction ─────────────────────────────────────────────────────\n\nfunction escapeRegex(str: string): string {\n\treturn str.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\n/**\n * Extracts artifact content from agent response text.\n * Used when a readonly role outputs markdown artifacts as text.\n *\n * Extraction strategies:\n * 1. Extract from ```artifactName code block (with nested fence pairing)\n * 2. Extract from ## artifactName section\n * 3. Return the entire response if it's a single output\n */\nexport function extractArtifactContent(\n\tresponseText: string,\n\tartifactName: string,\n\tisSingleOutput: boolean = false,\n): string | null {\n\tif (!responseText.trim()) {\n\t\treturn null;\n\t}\n\n\t// Pattern 1: ```artifactName\\n...\\n``` with nested code fence pairing.\n\t// A simple non-greedy regex fails when the content itself contains ``` fences\n\t// (e.g., directory trees or code examples inside a project-context.md artifact).\n\t// Instead, we find the opening fence and then iterate through subsequent fence\n\t// markers, pairing them (inner-open, inner-close) until we find the unpaired\n\t// closing fence for the outer block.\n\tconst content1 = extractFromCodeFence(responseText, artifactName);\n\tif (content1 !== null) {\n\t\treturn content1;\n\t}\n\n\t// Pattern 2: Content after ## artifactName (without m flag so $ matches end of string)\n\tconst pattern2 = new RegExp(`##\\\\s+${escapeRegex(artifactName)}\\\\s*\\\\n([\\\\s\\\\S]*?)(?=\\\\n##\\\\s|$)`);\n\tconst match2 = pattern2.exec(responseText);\n\tif (match2) {\n\t\treturn match2[1].trim();\n\t}\n\n\t// Pattern 3: Use the entire response if it's a single output\n\tif (isSingleOutput) {\n\t\treturn responseText.trim();\n\t}\n\n\treturn null;\n}\n\n/**\n * Extracts content from a fenced code block that may contain nested code fences.\n *\n * Algorithm:\n * 1. Find the opening fence (``` followed by artifactName)\n * 2. After the opening, scan for all ``` markers on their own lines\n * 3. Inner fences pair up sequentially (open+close). The first unpaired marker\n *    is the closing fence of the outer block.\n */\nfunction extractFromCodeFence(text: string, artifactName: string): string | null {\n\t// Match the opening fence line: ```artifactName (possibly with trailing whitespace)\n\tconst openPattern = new RegExp(`^(\\`{3,})${escapeRegex(artifactName)}[ \\\\t]*$`, \"m\");\n\tconst openMatch = openPattern.exec(text);\n\tif (!openMatch) {\n\t\treturn null;\n\t}\n\n\tconst openTickCount = openMatch[1].length;\n\tconst contentStart = openMatch.index + openMatch[0].length + 1; // +1 for the newline\n\n\t// Collect fence markers after the opening fence, stopping at the next\n\t// artifact-level opening fence (a fence whose info string looks like a\n\t// file path — contains '.' or '/'). This prevents consuming fences that\n\t// belong to subsequent artifacts in multi-artifact responses.\n\tconst rest = text.slice(contentStart);\n\tconst fencePattern = /^(`{3,})[ \\t]*(\\S*)?[ \\t]*$/gm;\n\n\tinterface FenceMarker {\n\t\tindex: number;\n\t\ttickCount: number;\n\t\tinfoString: string;\n\t}\n\n\tconst markers: FenceMarker[] = [];\n\tfor (;;) {\n\t\tconst match = fencePattern.exec(rest);\n\t\tif (match === null) break;\n\t\tconst infoString = match[2] || \"\";\n\n\t\t// Stop at the next artifact-level opening fence (file-like info string)\n\t\tif (infoString !== \"\" && isArtifactInfoString(infoString)) {\n\t\t\tbreak;\n\t\t}\n\n\t\tmarkers.push({\n\t\t\tindex: match.index,\n\t\t\ttickCount: match[1].length,\n\t\t\tinfoString,\n\t\t});\n\t}\n\n\tif (markers.length === 0) {\n\t\treturn null;\n\t}\n\n\t// Within the bounded markers, find the outer closing fence.\n\t// Use the last bare fence (no info string) with >= openTickCount backticks.\n\t// Inner bare fences pair up (open+close) before it; the remaining one is\n\t// the outer close.\n\tfor (let i = markers.length - 1; i >= 0; i--) {\n\t\tconst m = markers[i];\n\t\tif (m.infoString === \"\" && m.tickCount >= openTickCount) {\n\t\t\tconst content = rest.slice(0, m.index);\n\t\t\treturn content.trim();\n\t\t}\n\t}\n\n\t// No valid closing fence found — return null (fall through to other patterns)\n\treturn null;\n}\n\n/**\n * Determines if a code fence info string looks like an artifact file path\n * rather than a code language identifier.\n *\n * Artifact info strings contain '.' (file extension) or '/' (path separator),\n * e.g., \"spec.md\", \"feat-auth/spec.md\", \"plan.json\".\n * Code language info strings are simple identifiers like \"python\", \"bash\", \"json\", \"text\".\n */\nfunction isArtifactInfoString(infoString: string): boolean {\n\treturn infoString.includes(\".\") || infoString.includes(\"/\");\n}\n\n// ─── Skill Search Instructions ───────────────────────────────────────────────\n\n/**\n * Instructions for searching past artifacts to add to specific actions when availableSkills is present.\n * The \"past feature artifacts\" keyword matches the qmd-memory description in Available Skills.\n */\nconst SKILL_SEARCH_INSTRUCTIONS: Readonly<Record<string, string>> = {\n\tplan: \"Before planning, search past feature artifacts for similar features, design patterns, or recurring decisions.\",\n\tdesign: \"Before designing, search past feature artifacts for related design patterns and architectural decisions.\",\n\ttest: \"Search past feature artifacts for related test patterns, integration points, and previously discovered defects before writing tests.\",\n\tregression:\n\t\t\"Search past feature artifacts for areas previously affected by regressions before running regression tests.\",\n\treview: \"Search past feature artifacts for recurring review feedback and common issues before reviewing.\",\n\tinvestigate: \"Search past feature artifacts for similar issues and prior investigation findings.\",\n\tdiagnose: \"Search past feature artifacts for similar bug patterns and fix strategies.\",\n};\n\n// ─── Action Prompt Builder ───────────────────────────────────────────────────\n\n/**\n * Builds the prompt to send to the agent based on the step's agent role and action.\n */\nexport function buildActionPrompt(\n\tstep: PipelineStep,\n\tfeatureId: string,\n\tinputContent: string,\n\tartifactDir: string,\n\tavailableSkills?: string,\n\tbaseBranch?: string,\n\ttestingConfig?: TestingConfig,\n\tprojectRoot?: string,\n): string {\n\tconst parts: string[] = [];\n\n\tparts.push(`You are working on feature \"${featureId}\".`);\n\tif (projectRoot) {\n\t\tparts.push(\n\t\t\t`The project root is \\`${projectRoot}\\`. All tool commands (bash, read, write, edit) ` +\n\t\t\t\t`execute relative to this directory. Do NOT prefix commands with \\`cd\\` to a different base directory.`,\n\t\t);\n\t}\n\tparts.push(\"\");\n\tparts.push(`## Task: ${step.action}`);\n\tparts.push(\"\");\n\tparts.push(getActionInstructions(step.agent, step.action, baseBranch));\n\n\tif (availableSkills) {\n\t\tconst skillInstruction = SKILL_SEARCH_INSTRUCTIONS[step.action];\n\t\tif (skillInstruction) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(skillInstruction);\n\t\t}\n\t}\n\n\tif (inputContent) {\n\t\tparts.push(\"\");\n\t\tparts.push(\"## Input Artifacts\");\n\t\tparts.push(\"\");\n\t\tparts.push(inputContent);\n\t}\n\n\tif (step.outputs.length > 0) {\n\t\tparts.push(\"\");\n\t\tparts.push(\"## Output Artifacts\");\n\t\tparts.push(\"\");\n\t\tparts.push(\"You must produce the following artifacts:\");\n\t\tfor (const output of step.outputs) {\n\t\t\tparts.push(`- \\`${output}\\` → \\`${artifactDir}/${output}\\``);\n\t\t}\n\n\t\tif (isReadonlyRole(step.agent)) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\n\t\t\t\t\"Since you cannot write files directly, output the content of each artifact \" +\n\t\t\t\t\t\"in a markdown code block with the artifact filename as the info string. \" +\n\t\t\t\t\t\"For example: ```spec.md\\\\n(content)\\\\n```\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"Write each artifact directly to the specified file path using your tools.\");\n\t\t}\n\t}\n\n\t// Inject testing config for developer and tester actions\n\tif (testingConfig?.testCommand) {\n\t\tconst shouldInject =\n\t\t\t(step.agent === \"developer\" && (step.action === \"implement\" || step.action === \"fix\")) ||\n\t\t\t(step.agent === \"tester\" && (step.action === \"test\" || step.action === \"regression\"));\n\n\t\tif (shouldInject) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"## Project Test Configuration\");\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(`- **Test command**: \\`${testingConfig.testCommand}\\``);\n\t\t\tparts.push(`- **Timeout**: ${testingConfig.testTimeout} seconds`);\n\t\t\tparts.push(`- **Run existing tests**: ${testingConfig.runExistingTests}`);\n\t\t\tif (testingConfig.excludePatterns.length > 0) {\n\t\t\t\tparts.push(`- **Exclude patterns**: ${testingConfig.excludePatterns.join(\", \")}`);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Inject CI checks for developer and tester actions (tester can write/edit files too)\n\tif (testingConfig?.ciChecks && testingConfig.ciChecks.length > 0) {\n\t\tconst shouldInjectCiChecks =\n\t\t\t(step.agent === \"developer\" && (step.action === \"implement\" || step.action === \"fix\")) ||\n\t\t\t(step.agent === \"tester\" && (step.action === \"test\" || step.action === \"regression\"));\n\n\t\tif (shouldInjectCiChecks) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"## CI Verification Commands\");\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\n\t\t\t\t\"You MUST run the following checks after implementation. All must pass before the task is complete.\",\n\t\t\t);\n\t\t\tparts.push(\"\");\n\t\t\tfor (const check of testingConfig.ciChecks) {\n\t\t\t\tparts.push(`- **${check.name}**: \\`${check.command}\\``);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Returns instructions for the given action.\n */\nfunction getActionInstructions(agent: AgentRole, action: string, baseBranch?: string): string {\n\tswitch (action) {\n\t\tcase \"plan\":\n\t\t\treturn \"Analyze the requirements and decompose them into features. Produce a spec.md for each feature and update plan.json.\";\n\n\t\tcase \"design\":\n\t\t\treturn \"Read the spec and produce a detailed design document with file structure, interfaces, and implementation guide.\";\n\n\t\tcase \"implement\":\n\t\t\treturn \"Implement the feature according to the spec and design documents. Write source code files and ensure they compile.\";\n\n\t\tcase \"fix\":\n\t\t\treturn \"Fix the bug as described in the diagnosis. Apply the minimal change necessary.\";\n\n\t\tcase \"test\":\n\t\t\treturn \"Write comprehensive tests for the feature and run them. Produce a test-report.md with results.\";\n\n\t\tcase \"regression\":\n\t\t\treturn \"Run existing tests to verify no regressions were introduced. Produce a regression-report.md with results.\";\n\n\t\tcase \"review\":\n\t\t\treturn \"Review the implementation for correctness, quality, architecture compliance, and standards compliance. Produce a review.md with your verdict.\";\n\n\t\tcase \"branch\":\n\t\t\treturn baseBranch\n\t\t\t\t? `Create a feature branch from \\`${baseBranch}\\`. Run \\`git checkout ${baseBranch}\\` first, then create the branch.`\n\t\t\t\t: `Create a feature branch for ${agent === \"cicd\" ? \"this feature\" : \"the implementation\"}.`;\n\n\t\tcase \"merge\":\n\t\t\treturn baseBranch\n\t\t\t\t? `Merge the feature branch into \\`${baseBranch}\\` using \\`--no-ff\\`. Run \\`git checkout ${baseBranch}\\` first, then merge. Do NOT run \\`git push\\` — push is handled by the orchestration system.`\n\t\t\t\t: \"Merge the feature branch after all checks pass. Do NOT run `git push`.\";\n\n\t\tcase \"analyze\":\n\t\t\treturn \"Analyze the impact of the proposed change on the existing codebase. Produce an impact-report.md.\";\n\n\t\tcase \"investigate\":\n\t\t\treturn \"Trace through the code to identify the root cause of the issue. Use read and bash tools to explore the codebase, run tests, add debug output if needed. Do not produce any artifacts — this is an exploratory step. Your findings will inform the subsequent diagnosis step.\";\n\n\t\tcase \"diagnose\":\n\t\t\treturn \"Analyze the bug, reproduce it, identify the root cause, and produce a diagnosis.md.\";\n\n\t\tdefault:\n\t\t\treturn `Execute the \"${action}\" task for this feature.`;\n\t}\n}\n\n// ─── Default Step Executor ───────────────────────────────────────────────────\n\n/**\n * Default StepExecutor implementation.\n * Creates a role-specific agent, passes input artifacts as context,\n * runs the agent, and saves the output artifacts.\n */\nexport const defaultStepExecutor: StepExecutor = async (step, featureId, context) => {\n\tconst { store, config, projectRoot } = context;\n\tconst log = createModuleLogger(context.logger ?? noopLogger, \"step-executor\");\n\n\t// 1. Ensure feature directory exists\n\tawait store.ensureFeatureDir(featureId);\n\n\t// 2. Load input artifacts\n\tlog.debug(`Loading input artifacts: [${step.inputs.join(\", \")}]`, { featureId, agent: step.agent });\n\tlet inputContent = await loadInputArtifacts(step.inputs, featureId, context);\n\n\t// 2b. Inject system-design.md for architect and reviewer roles (system-level architecture context)\n\tif ((step.agent === \"architect\" || step.agent === \"reviewer\") && (await store.hasSystemDesign())) {\n\t\tconst systemDesign = await store.readSystemDesign();\n\t\tconst systemDesignSection = `## Input: system-design.md (System Architecture)\\n\\n${systemDesign}`;\n\t\tinputContent = inputContent ? `${inputContent}\\n\\n---\\n\\n${systemDesignSection}` : systemDesignSection;\n\t\tlog.debug(`Injected system-design.md into ${step.agent} context`, { featureId });\n\t}\n\n\t// 3. Get system prompt\n\tconst systemPrompt = getSystemPromptForRole(step.agent);\n\n\t// 4. Artifact directory path\n\tconst artifactDir = store.getFeatureDir(featureId);\n\n\t// 5. Build execution prompt\n\tlet actionPrompt = buildActionPrompt(\n\t\tstep,\n\t\tfeatureId,\n\t\tinputContent,\n\t\tartifactDir,\n\t\tcontext.availableSkills,\n\t\tconfig.baseBranch,\n\t\tconfig.testing,\n\t\tprojectRoot,\n\t);\n\n\t// 6a. Load prior action history for the same role (only when step opts in)\n\tlet initialMessages: import(\"@mariozechner/pi-agent-core\").AgentMessage[] | undefined;\n\tif (step.inheritPriorHistory) {\n\t\tconst priorCheckpoints = await store.loadPriorAgentHistory(featureId, step.agent, step.action);\n\t\tif (priorCheckpoints.length > 0) {\n\t\t\tlog.debug(`Loading prior action history for ${step.agent}: ${priorCheckpoints.length} checkpoint(s)`, {\n\t\t\t\tfeatureId,\n\t\t\t\tagent: step.agent,\n\t\t\t});\n\t\t\tinitialMessages = priorCheckpoints.flatMap((cp) => cp.messages);\n\t\t}\n\t}\n\n\t// 6b. If retry history exists for the current action, append it (checkpoint restoration on retry)\n\tconst hasHistory = await store.hasAgentHistory(featureId, step.agent, step.action);\n\tif (hasHistory) {\n\t\tconst checkpoint = await store.loadAgentHistory(featureId, step.agent, step.action);\n\t\tif (checkpoint) {\n\t\t\tinitialMessages = [...(initialMessages ?? []), ...checkpoint.messages];\n\t\t\tactionPrompt = `[RETRY] Previous attempt for this step exists in your conversation history. Review what went wrong and try a different approach.\\n\\n${actionPrompt}`;\n\t\t}\n\t}\n\n\t// 7. Create agent (inject prior history)\n\tlog.info(`Creating agent: ${step.agent} for action: ${step.action}`, { featureId, hasHistory: !!initialMessages });\n\tconst agent = await createRoleAgent({\n\t\trole: step.agent,\n\t\tsystemPrompt,\n\t\tconfig,\n\t\tprojectRoot,\n\t\tmodel: context.model,\n\t\tfeatureContext: inputContent || undefined,\n\t\tgetApiKey: context.getApiKey,\n\t\tinitialMessages,\n\t\tavailableSkills: context.availableSkills,\n\t\tprojectContext: context.projectContext,\n\t});\n\n\t// 8. Agent registration callback\n\tcontext.onAgentCreated?.(agent);\n\n\ttry {\n\t\t// 9. Run agent (with history)\n\t\tlog.info(`Agent executing: ${step.agent}:${step.action}`, { featureId });\n\t\tconst result = await runAgentWithHistory(agent, actionPrompt);\n\n\t\t// 9b. Aggregate token usage\n\t\tcontext.lastStepUsage = aggregateUsage(result.messages);\n\n\t\t// 10. Save history checkpoint\n\t\tawait store.saveAgentHistory(featureId, {\n\t\t\trole: step.agent,\n\t\t\taction: step.action,\n\t\t\tmessages: filterSerializableMessages(result.messages),\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t});\n\n\t\t// 11. Save artifacts for readonly roles\n\t\tif (isReadonlyRole(step.agent) && step.outputs.length > 0) {\n\t\t\tconst isSingle = step.outputs.length === 1;\n\t\t\tfor (const output of step.outputs) {\n\t\t\t\tconst content = extractArtifactContent(result.text, output, isSingle);\n\t\t\t\tif (content) {\n\t\t\t\t\tlog.debug(`Extracted artifact: ${output}`, { featureId, agent: step.agent });\n\t\t\t\t\tawait store.writeArtifact(featureId, output as ArtifactName, content);\n\t\t\t\t} else {\n\t\t\t\t\tlog.warn(`Failed to extract artifact: ${output}`, { featureId, agent: step.agent });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tlog.info(`Agent completed: ${step.agent}:${step.action}`, { featureId });\n\t} finally {\n\t\t// 12. Agent release callback\n\t\tcontext.onAgentFinished?.();\n\t}\n};\n"]}
+{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAgB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAchG,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEvD;AAID,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,SAAS,CAMrD,CAAC;AAIH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,SAAS,CA8B9E;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBnH;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACrC,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC7B,MAAM,GAAG,IAAI,CA6Bf;AAuFD,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACpB;AAYD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsDvF;AAID;;GAEG;AACH,wBAAgB,iBAAiB,CAChC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,GAClB,MAAM,CAoFR;AAwFD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAuIjC,CAAC","sourcesContent":["import { access, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport type { AgentMessage } from \"@mariozechner/pi-agent-core\";\nimport { createRoleAgent, filterSerializableMessages, runAgentWithHistory } from \"./agent-factory.js\";\nimport { createModuleLogger, noopLogger } from \"./logger.js\";\nimport type { StepContext, StepExecutor, StepUsage } from \"./pipeline.js\";\nimport { getSystemPromptForRole } from \"./roles/index.js\";\nimport type { AgentRole, ArtifactName, CiCheck, PipelineStep, TestingConfig } from \"./types.js\";\n\n// ─── Readonly Role Detection ─────────────────────────────────────────────────\n\n/** Roles that cannot write files via tools. Artifacts are extracted from the response and saved to the store. */\nconst READONLY_ROLES: ReadonlySet<AgentRole> = new Set<AgentRole>([\n\t\"planner\",\n\t\"analyzer\",\n\t\"reviewer\",\n\t\"diagnostician\",\n\t\"discovery\",\n\t\"projectAnalyzer\",\n]);\n\n/** Determines whether the role is readonly (cannot write files via tools). */\nexport function isReadonlyRole(role: AgentRole): boolean {\n\treturn READONLY_ROLES.has(role);\n}\n\n// ─── System Design Injection ─────────────────────────────────────────────────\n\n/** Roles that receive system-design.md as additional input context. */\nexport const SYSTEM_DESIGN_ROLES: ReadonlySet<AgentRole> = new Set<AgentRole>([\n\t\"architect\",\n\t\"reviewer\",\n\t\"developer\",\n\t\"tester\",\n\t\"diagnostician\",\n]);\n\n// ─── Usage Aggregation ───────────────────────────────────────────────────────\n\n/**\n * Aggregates token usage from all assistant messages in a conversation.\n * Returns undefined if no assistant messages with usage data are found.\n */\nexport function aggregateUsage(messages: AgentMessage[]): StepUsage | undefined {\n\tlet input = 0;\n\tlet output = 0;\n\tlet cacheRead = 0;\n\tlet cacheWrite = 0;\n\tlet totalTokens = 0;\n\tlet cost = 0;\n\tlet found = false;\n\n\tfor (const msg of messages) {\n\t\tif (msg.role === \"assistant\" && \"usage\" in msg && msg.usage) {\n\t\t\tconst u = msg.usage as {\n\t\t\t\tinput: number;\n\t\t\t\toutput: number;\n\t\t\t\tcacheRead: number;\n\t\t\t\tcacheWrite: number;\n\t\t\t\ttotalTokens: number;\n\t\t\t\tcost: { total: number };\n\t\t\t};\n\t\t\tfound = true;\n\t\t\tinput += u.input;\n\t\t\toutput += u.output;\n\t\t\tcacheRead += u.cacheRead;\n\t\t\tcacheWrite += u.cacheWrite;\n\t\t\ttotalTokens += u.totalTokens;\n\t\t\tcost += u.cost.total;\n\t\t}\n\t}\n\n\treturn found ? { input, output, cacheRead, cacheWrite, totalTokens, cost } : undefined;\n}\n\n// ─── Input Artifact Loader ───────────────────────────────────────────────────\n\n/**\n * Reads the artifact files specified in step.inputs from the store\n * and combines them into a single context string.\n * Non-existent files are skipped.\n */\nexport async function loadInputArtifacts(inputs: string[], featureId: string, context: StepContext): Promise<string> {\n\tif (inputs.length === 0) {\n\t\treturn \"\";\n\t}\n\n\tconst sections: string[] = [];\n\n\tfor (const input of inputs) {\n\t\tconst hasFile = await context.store.hasArtifact(featureId, input as ArtifactName);\n\t\tif (!hasFile) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst content = await context.store.readArtifact(featureId, input as ArtifactName);\n\t\tsections.push(`## Input: ${input}\\n\\n${content}`);\n\t}\n\n\treturn sections.join(\"\\n\\n---\\n\\n\");\n}\n\n// ─── Artifact Extraction ─────────────────────────────────────────────────────\n\nfunction escapeRegex(str: string): string {\n\treturn str.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\n/**\n * Extracts artifact content from agent response text.\n * Used when a readonly role outputs markdown artifacts as text.\n *\n * Extraction strategies:\n * 1. Extract from ```artifactName code block (with nested fence pairing)\n * 2. Extract from ## artifactName section\n * 3. Return the entire response if it's a single output\n */\nexport function extractArtifactContent(\n\tresponseText: string,\n\tartifactName: string,\n\tisSingleOutput: boolean = false,\n): string | null {\n\tif (!responseText.trim()) {\n\t\treturn null;\n\t}\n\n\t// Pattern 1: ```artifactName\\n...\\n``` with nested code fence pairing.\n\t// A simple non-greedy regex fails when the content itself contains ``` fences\n\t// (e.g., directory trees or code examples inside a project-context.md artifact).\n\t// Instead, we find the opening fence and then iterate through subsequent fence\n\t// markers, pairing them (inner-open, inner-close) until we find the unpaired\n\t// closing fence for the outer block.\n\tconst content1 = extractFromCodeFence(responseText, artifactName);\n\tif (content1 !== null) {\n\t\treturn content1;\n\t}\n\n\t// Pattern 2: Content after ## artifactName (without m flag so $ matches end of string)\n\tconst pattern2 = new RegExp(`##\\\\s+${escapeRegex(artifactName)}\\\\s*\\\\n([\\\\s\\\\S]*?)(?=\\\\n##\\\\s|$)`);\n\tconst match2 = pattern2.exec(responseText);\n\tif (match2) {\n\t\treturn match2[1].trim();\n\t}\n\n\t// Pattern 3: Use the entire response if it's a single output\n\tif (isSingleOutput) {\n\t\treturn responseText.trim();\n\t}\n\n\treturn null;\n}\n\n/**\n * Extracts content from a fenced code block that may contain nested code fences.\n *\n * Algorithm:\n * 1. Find the opening fence (``` followed by artifactName)\n * 2. After the opening, scan for all ``` markers on their own lines\n * 3. Inner fences pair up sequentially (open+close). The first unpaired marker\n *    is the closing fence of the outer block.\n */\nfunction extractFromCodeFence(text: string, artifactName: string): string | null {\n\t// Match the opening fence line: ```artifactName (possibly with trailing whitespace)\n\tconst openPattern = new RegExp(`^(\\`{3,})${escapeRegex(artifactName)}[ \\\\t]*$`, \"m\");\n\tconst openMatch = openPattern.exec(text);\n\tif (!openMatch) {\n\t\treturn null;\n\t}\n\n\tconst openTickCount = openMatch[1].length;\n\tconst contentStart = openMatch.index + openMatch[0].length + 1; // +1 for the newline\n\n\t// Collect fence markers after the opening fence, stopping at the next\n\t// artifact-level opening fence (a fence whose info string looks like a\n\t// file path — contains '.' or '/'). This prevents consuming fences that\n\t// belong to subsequent artifacts in multi-artifact responses.\n\tconst rest = text.slice(contentStart);\n\tconst fencePattern = /^(`{3,})[ \\t]*(\\S*)?[ \\t]*$/gm;\n\n\tinterface FenceMarker {\n\t\tindex: number;\n\t\ttickCount: number;\n\t\tinfoString: string;\n\t}\n\n\tconst markers: FenceMarker[] = [];\n\tfor (;;) {\n\t\tconst match = fencePattern.exec(rest);\n\t\tif (match === null) break;\n\t\tconst infoString = match[2] || \"\";\n\n\t\t// Stop at the next artifact-level opening fence (file-like info string)\n\t\tif (infoString !== \"\" && isArtifactInfoString(infoString)) {\n\t\t\tbreak;\n\t\t}\n\n\t\tmarkers.push({\n\t\t\tindex: match.index,\n\t\t\ttickCount: match[1].length,\n\t\t\tinfoString,\n\t\t});\n\t}\n\n\tif (markers.length === 0) {\n\t\treturn null;\n\t}\n\n\t// Within the bounded markers, find the outer closing fence.\n\t// Use the last bare fence (no info string) with >= openTickCount backticks.\n\t// Inner bare fences pair up (open+close) before it; the remaining one is\n\t// the outer close.\n\tfor (let i = markers.length - 1; i >= 0; i--) {\n\t\tconst m = markers[i];\n\t\tif (m.infoString === \"\" && m.tickCount >= openTickCount) {\n\t\t\tconst content = rest.slice(0, m.index);\n\t\t\treturn content.trim();\n\t\t}\n\t}\n\n\t// No valid closing fence found — return null (fall through to other patterns)\n\treturn null;\n}\n\n/**\n * Determines if a code fence info string looks like an artifact file path\n * rather than a code language identifier.\n *\n * Artifact info strings contain '.' (file extension) or '/' (path separator),\n * e.g., \"spec.md\", \"feat-auth/spec.md\", \"plan.json\".\n * Code language info strings are simple identifiers like \"python\", \"bash\", \"json\", \"text\".\n */\nfunction isArtifactInfoString(infoString: string): boolean {\n\treturn infoString.includes(\".\") || infoString.includes(\"/\");\n}\n\n// ─── Lightweight Test Config Detection ───────────────────────────────────────\n\n/** Result of lightweight test config detection from project files. */\nexport interface DetectedTestConfig {\n\ttestCommand?: string;\n\tciChecks: CiCheck[];\n}\n\n/** Checks whether a file exists at the given path. */\nasync function fileExistsAt(path: string): Promise<boolean> {\n\ttry {\n\t\tawait access(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/**\n * Detects test command and CI checks from project files when config.testing is empty.\n * This is a fast file-existence check — NOT a full project-analyze re-run.\n * Used for new projects where project-analyze ran before the project scaffold existed.\n */\nexport async function detectTestConfig(projectRoot: string): Promise<DetectedTestConfig> {\n\tconst result: DetectedTestConfig = { ciChecks: [] };\n\n\t// 1. Read package.json scripts.test\n\ttry {\n\t\tconst raw = await readFile(join(projectRoot, \"package.json\"), \"utf-8\");\n\t\tconst pkg = JSON.parse(raw) as { scripts?: Record<string, string> };\n\t\tconst testScript = pkg.scripts?.test;\n\t\tif (testScript && testScript !== 'echo \"Error: no test specified\" && exit 1') {\n\t\t\tresult.testCommand = testScript;\n\t\t}\n\t} catch {\n\t\t/* no package.json */\n\t}\n\n\t// 2. Check for vitest/jest config → fallback test command\n\tif (!result.testCommand) {\n\t\tconst testConfigs: Array<{ file: string; command: string }> = [\n\t\t\t{ file: \"vitest.config.ts\", command: \"npx vitest run\" },\n\t\t\t{ file: \"vitest.config.js\", command: \"npx vitest run\" },\n\t\t\t{ file: \"vite.config.ts\", command: \"npx vitest run\" },\n\t\t\t{ file: \"jest.config.ts\", command: \"npx jest\" },\n\t\t\t{ file: \"jest.config.js\", command: \"npx jest\" },\n\t\t];\n\t\tfor (const { file, command } of testConfigs) {\n\t\t\tif (await fileExistsAt(join(projectRoot, file))) {\n\t\t\t\tresult.testCommand = command;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\t// 3. Check for tsconfig.json → tsc CI check\n\tif (await fileExistsAt(join(projectRoot, \"tsconfig.json\"))) {\n\t\tresult.ciChecks.push({ name: \"TypeScript\", command: \"npx tsc --noEmit\" });\n\t}\n\n\t// 4. Check for eslint config → eslint CI check\n\tconst eslintConfigs = [\n\t\t\"eslint.config.js\",\n\t\t\"eslint.config.ts\",\n\t\t\"eslint.config.mjs\",\n\t\t\".eslintrc.js\",\n\t\t\".eslintrc.json\",\n\t\t\".eslintrc.yml\",\n\t];\n\tfor (const file of eslintConfigs) {\n\t\tif (await fileExistsAt(join(projectRoot, file))) {\n\t\t\tresult.ciChecks.push({ name: \"ESLint\", command: \"npx eslint .\" });\n\t\t\tbreak;\n\t\t}\n\t}\n\n\treturn result;\n}\n\n// ─── Action Prompt Builder ───────────────────────────────────────────────────\n\n/**\n * Builds the prompt to send to the agent based on the step's agent role and action.\n */\nexport function buildActionPrompt(\n\tstep: PipelineStep,\n\tfeatureId: string,\n\tinputContent: string,\n\tartifactDir: string,\n\tbaseBranch?: string,\n\ttestingConfig?: TestingConfig,\n\tprojectRoot?: string,\n): string {\n\tconst parts: string[] = [];\n\n\tparts.push(`You are working on feature \"${featureId}\".`);\n\tif (projectRoot) {\n\t\tparts.push(\n\t\t\t`The project root is \\`${projectRoot}\\`. All tool commands (bash, read, write, edit) ` +\n\t\t\t\t`execute relative to this directory. Do NOT prefix commands with \\`cd\\` to a different base directory.`,\n\t\t);\n\t}\n\tparts.push(\"\");\n\tparts.push(`## Task: ${step.action}`);\n\tparts.push(\"\");\n\tparts.push(getActionInstructions(step.agent, step.action, baseBranch));\n\n\tif (inputContent) {\n\t\tparts.push(\"\");\n\t\tparts.push(\"## Input Artifacts\");\n\t\tparts.push(\"\");\n\t\tparts.push(inputContent);\n\t}\n\n\tif (step.outputs.length > 0) {\n\t\tparts.push(\"\");\n\t\tparts.push(\"## Output Artifacts\");\n\t\tparts.push(\"\");\n\t\tparts.push(\"You must produce the following artifacts:\");\n\t\tfor (const output of step.outputs) {\n\t\t\tparts.push(`- \\`${output}\\` → \\`${artifactDir}/${output}\\``);\n\t\t}\n\n\t\tif (isReadonlyRole(step.agent)) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\n\t\t\t\t\"Since you cannot write files directly, output the content of each artifact \" +\n\t\t\t\t\t\"in a markdown code block with the artifact filename as the info string. \" +\n\t\t\t\t\t\"For example: ```spec.md\\\\n(content)\\\\n```\",\n\t\t\t);\n\t\t} else {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"Write each artifact directly to the specified file path using your tools.\");\n\t\t}\n\t}\n\n\t// Inject testing config for developer and tester actions\n\tif (testingConfig?.testCommand) {\n\t\tconst shouldInject =\n\t\t\t(step.agent === \"developer\" && (step.action === \"implement\" || step.action === \"fix\")) ||\n\t\t\t(step.agent === \"tester\" && (step.action === \"test\" || step.action === \"regression\"));\n\n\t\tif (shouldInject) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"## Project Test Configuration\");\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(`- **Test command**: \\`${testingConfig.testCommand}\\``);\n\t\t\tparts.push(`- **Timeout**: ${testingConfig.testTimeout} seconds`);\n\t\t\tparts.push(`- **Run existing tests**: ${testingConfig.runExistingTests}`);\n\t\t\tif (testingConfig.excludePatterns.length > 0) {\n\t\t\t\tparts.push(`- **Exclude patterns**: ${testingConfig.excludePatterns.join(\", \")}`);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Inject CI checks for developer and tester actions (tester can write/edit files too)\n\tif (testingConfig?.ciChecks && testingConfig.ciChecks.length > 0) {\n\t\tconst shouldInjectCiChecks =\n\t\t\t(step.agent === \"developer\" && (step.action === \"implement\" || step.action === \"fix\")) ||\n\t\t\t(step.agent === \"tester\" && (step.action === \"test\" || step.action === \"regression\"));\n\n\t\tif (shouldInjectCiChecks) {\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\"## CI Verification Commands\");\n\t\t\tparts.push(\"\");\n\t\t\tparts.push(\n\t\t\t\t\"You MUST run the following checks after implementation. All must pass before the task is complete.\",\n\t\t\t);\n\t\t\tparts.push(\"\");\n\t\t\tfor (const check of testingConfig.ciChecks) {\n\t\t\t\tparts.push(`- **${check.name}**: \\`${check.command}\\``);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn parts.join(\"\\n\");\n}\n\n/**\n * Returns instructions for the given action.\n */\nfunction getActionInstructions(agent: AgentRole, action: string, baseBranch?: string): string {\n\tswitch (action) {\n\t\tcase \"plan\":\n\t\t\treturn \"Analyze the requirements and decompose them into features. Produce a spec.md for each feature and update plan.json.\";\n\n\t\tcase \"design\":\n\t\t\treturn \"Read the spec and produce a detailed design document with file structure, interfaces, and implementation guide.\";\n\n\t\tcase \"implement\":\n\t\t\treturn \"Implement the feature according to the spec and design documents. Write source code files and ensure they compile.\";\n\n\t\tcase \"fix\":\n\t\t\treturn \"Fix the bug as described in the diagnosis. Apply the minimal change necessary.\";\n\n\t\tcase \"test\":\n\t\t\treturn baseBranch\n\t\t\t\t? \"Write comprehensive tests for the feature and run them. Produce a test-report.md with results.\\n\\n\" +\n\t\t\t\t\t\t`**Execution order**: ` +\n\t\t\t\t\t\t`1) Run \\`git diff ${baseBranch}..HEAD --name-only\\` to identify changed files. ` +\n\t\t\t\t\t\t`2) Read the implementation files to understand types and interfaces. ` +\n\t\t\t\t\t\t`3) Write ALL test files before running anything. ` +\n\t\t\t\t\t\t`4) Run the test suite ONCE. If tests fail, fix all failures, then run ONCE more. ` +\n\t\t\t\t\t\t`5) Run CI verification commands (type-check, lint) ONCE at the end, after all tests pass. ` +\n\t\t\t\t\t\t`Do not interleave writing and running — batch all writes first, then run.`\n\t\t\t\t: \"Write comprehensive tests for the feature and run them. Produce a test-report.md with results.\\n\\n\" +\n\t\t\t\t\t\t\"**Execution order**: \" +\n\t\t\t\t\t\t\"1) Read the implementation files to understand types and interfaces. \" +\n\t\t\t\t\t\t\"2) Write ALL test files before running anything. \" +\n\t\t\t\t\t\t\"3) Run the test suite ONCE. If tests fail, fix all failures, then run ONCE more. \" +\n\t\t\t\t\t\t\"4) Run CI verification commands (type-check, lint) ONCE at the end, after all tests pass. \" +\n\t\t\t\t\t\t\"Do not interleave writing and running — batch all writes first, then run.\";\n\n\t\tcase \"regression\":\n\t\t\treturn baseBranch\n\t\t\t\t? \"Run existing tests to verify no regressions were introduced. Produce a regression-report.md with results.\\n\\n\" +\n\t\t\t\t\t\t`**Execution order**: ` +\n\t\t\t\t\t\t`1) Run \\`git diff ${baseBranch}..HEAD --name-only\\` to identify changed files and test files. ` +\n\t\t\t\t\t\t`2) Run the full test suite ONCE with a single command. ` +\n\t\t\t\t\t\t`3) Run CI verification commands (type-check, lint) ONCE at the end. ` +\n\t\t\t\t\t\t`Do not run tests file-by-file — use a single test runner invocation.`\n\t\t\t\t: \"Run existing tests to verify no regressions were introduced. Produce a regression-report.md with results.\\n\\n\" +\n\t\t\t\t\t\t\"**Execution order**: \" +\n\t\t\t\t\t\t\"1) Identify the test files to run from test-report.md. \" +\n\t\t\t\t\t\t\"2) Run the full test suite ONCE with a single command. \" +\n\t\t\t\t\t\t\"3) Run CI verification commands (type-check, lint) ONCE at the end. \" +\n\t\t\t\t\t\t\"Do not run tests file-by-file — use a single test runner invocation.\";\n\n\t\tcase \"review\":\n\t\t\treturn baseBranch\n\t\t\t\t? `Review the implementation for correctness, quality, architecture compliance, and standards compliance. Produce a review.md with your verdict.\\n\\n` +\n\t\t\t\t\t\t`**Start by running \\`git diff ${baseBranch}..HEAD\\`** to see all changes at once. ` +\n\t\t\t\t\t\t`Use \\`git diff --stat ${baseBranch}..HEAD\\` for an overview.`\n\t\t\t\t: \"Review the implementation for correctness, quality, architecture compliance, and standards compliance. Produce a review.md with your verdict.\";\n\n\t\tcase \"branch\":\n\t\t\treturn baseBranch\n\t\t\t\t? `Create a feature branch from \\`${baseBranch}\\`. Run \\`git checkout ${baseBranch}\\` first, then create the branch.`\n\t\t\t\t: `Create a feature branch for ${agent === \"cicd\" ? \"this feature\" : \"the implementation\"}.`;\n\n\t\tcase \"merge\":\n\t\t\treturn baseBranch\n\t\t\t\t? `Merge the feature branch into \\`${baseBranch}\\` using \\`--no-ff\\`.\\n\\n` +\n\t\t\t\t\t\t`**Start by running \\`git diff ${baseBranch}..HEAD --name-only\\`** to get the complete list of changed files. ` +\n\t\t\t\t\t\t`Use this list for \\`git add\\` in a single command — do NOT use \\`ls\\`, \\`find\\`, or \\`git status\\` to discover files.\\n\\n` +\n\t\t\t\t\t\t`Run \\`git checkout ${baseBranch}\\` first, then merge. Do NOT run \\`git push\\` — push is handled by the orchestration system.`\n\t\t\t\t: \"Merge the feature branch after all checks pass. Do NOT run `git push`.\";\n\n\t\tcase \"analyze\":\n\t\t\treturn \"Analyze the impact of the proposed change on the existing codebase. Produce an impact-report.md.\";\n\n\t\tcase \"investigate\":\n\t\t\treturn \"Trace through the code to identify the root cause of the issue. Use read and bash tools to explore the codebase, run tests, add debug output if needed. Do not produce any artifacts — this is an exploratory step. Your findings will inform the subsequent diagnosis step.\";\n\n\t\tcase \"diagnose\":\n\t\t\treturn \"Analyze the bug, reproduce it, identify the root cause, and produce a diagnosis.md.\";\n\n\t\tdefault:\n\t\t\treturn `Execute the \"${action}\" task for this feature.`;\n\t}\n}\n\n// ─── Default Step Executor ───────────────────────────────────────────────────\n\n/**\n * Default StepExecutor implementation.\n * Creates a role-specific agent, passes input artifacts as context,\n * runs the agent, and saves the output artifacts.\n */\nexport const defaultStepExecutor: StepExecutor = async (step, featureId, context) => {\n\tconst { store, config, projectRoot } = context;\n\tconst log = createModuleLogger(context.logger ?? noopLogger, \"step-executor\");\n\n\t// 1. Ensure feature directory exists\n\tawait store.ensureFeatureDir(featureId);\n\n\t// 2. Load input artifacts\n\tlog.debug(`Loading input artifacts: [${step.inputs.join(\", \")}]`, { featureId, agent: step.agent });\n\tlet inputContent = await loadInputArtifacts(step.inputs, featureId, context);\n\n\t// 2b. Inject system-design.md for roles that need system-level architecture context\n\tif (SYSTEM_DESIGN_ROLES.has(step.agent) && (await store.hasSystemDesign())) {\n\t\tconst systemDesign = await store.readSystemDesign();\n\t\tconst systemDesignSection = `## Input: system-design.md (System Architecture)\\n\\n${systemDesign}`;\n\t\tinputContent = inputContent ? `${inputContent}\\n\\n---\\n\\n${systemDesignSection}` : systemDesignSection;\n\t\tlog.debug(`Injected system-design.md into ${step.agent} context`, { featureId });\n\t}\n\n\t// 3. Get system prompt\n\tconst systemPrompt = getSystemPromptForRole(step.agent);\n\n\t// 4. Artifact directory path\n\tconst artifactDir = store.getFeatureDir(featureId);\n\n\t// 4b. Lightweight test config detection for new projects\n\t// When config.testing.testCommand is empty (project-analyze ran before project existed),\n\t// detect from package.json and config files so the tester has concrete commands to use.\n\tlet effectiveTestingConfig = config.testing;\n\tif (\n\t\tstep.agent === \"tester\" &&\n\t\t(step.action === \"test\" || step.action === \"regression\") &&\n\t\t!config.testing?.testCommand\n\t) {\n\t\tconst detected = await detectTestConfig(projectRoot);\n\t\tif (detected.testCommand || detected.ciChecks.length > 0) {\n\t\t\teffectiveTestingConfig = {\n\t\t\t\ttestCommand: detected.testCommand ?? \"\",\n\t\t\t\ttestTimeout: config.testing?.testTimeout ?? 300,\n\t\t\t\trunExistingTests: config.testing?.runExistingTests ?? false,\n\t\t\t\texcludePatterns: config.testing?.excludePatterns ?? [],\n\t\t\t\tciChecks: [...(config.testing?.ciChecks ?? []), ...detected.ciChecks],\n\t\t\t};\n\t\t\tlog.debug(\n\t\t\t\t`Detected test config for new project: testCommand=${detected.testCommand ?? \"(none)\"}, ciChecks=${detected.ciChecks.length}`,\n\t\t\t\t{ featureId },\n\t\t\t);\n\t\t}\n\t}\n\n\t// 5. Build execution prompt\n\tlet actionPrompt = buildActionPrompt(\n\t\tstep,\n\t\tfeatureId,\n\t\tinputContent,\n\t\tartifactDir,\n\t\tconfig.baseBranch,\n\t\teffectiveTestingConfig,\n\t\tprojectRoot,\n\t);\n\n\t// 6a. Load prior action history for the same role (only when step opts in)\n\tlet initialMessages: import(\"@mariozechner/pi-agent-core\").AgentMessage[] | undefined;\n\tif (step.inheritPriorHistory) {\n\t\tconst priorCheckpoints = await store.loadPriorAgentHistory(featureId, step.agent, step.action);\n\t\tif (priorCheckpoints.length > 0) {\n\t\t\tlog.debug(`Loading prior action history for ${step.agent}: ${priorCheckpoints.length} checkpoint(s)`, {\n\t\t\t\tfeatureId,\n\t\t\t\tagent: step.agent,\n\t\t\t});\n\t\t\tinitialMessages = priorCheckpoints.flatMap((cp) => cp.messages);\n\t\t}\n\t}\n\n\t// 6b. If retry history exists for the current action, append it (checkpoint restoration on retry)\n\tconst hasHistory = await store.hasAgentHistory(featureId, step.agent, step.action);\n\tif (hasHistory) {\n\t\tconst checkpoint = await store.loadAgentHistory(featureId, step.agent, step.action);\n\t\tif (checkpoint) {\n\t\t\tinitialMessages = [...(initialMessages ?? []), ...checkpoint.messages];\n\t\t\tactionPrompt = `[RETRY] Previous attempt for this step exists in your conversation history. Review what went wrong and try a different approach.\\n\\n${actionPrompt}`;\n\t\t}\n\t}\n\n\t// 7. Create agent (inject prior history)\n\tlog.info(`Creating agent: ${step.agent} for action: ${step.action}`, { featureId, hasHistory: !!initialMessages });\n\tconst agent = await createRoleAgent({\n\t\trole: step.agent,\n\t\tsystemPrompt,\n\t\tconfig,\n\t\tprojectRoot,\n\t\tmodel: context.model,\n\t\tfeatureContext: inputContent || undefined,\n\t\tgetApiKey: context.getApiKey,\n\t\tinitialMessages,\n\t});\n\n\t// 8. Agent registration callback\n\tcontext.onAgentCreated?.(agent);\n\n\ttry {\n\t\t// 9. Run agent (with history)\n\t\tlog.info(`Agent executing: ${step.agent}:${step.action}`, { featureId });\n\t\tconst result = await runAgentWithHistory(agent, actionPrompt);\n\n\t\t// 9b. Aggregate token usage and capture response text\n\t\tcontext.lastStepUsage = aggregateUsage(result.messages);\n\t\tcontext.lastStepResponseText = result.text;\n\n\t\t// 10. Save history checkpoint\n\t\tawait store.saveAgentHistory(featureId, {\n\t\t\trole: step.agent,\n\t\t\taction: step.action,\n\t\t\tmessages: filterSerializableMessages(result.messages),\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t});\n\n\t\t// 11. Save artifacts for readonly roles\n\t\tif (isReadonlyRole(step.agent) && step.outputs.length > 0) {\n\t\t\tconst isSingle = step.outputs.length === 1;\n\t\t\tfor (const output of step.outputs) {\n\t\t\t\tconst content = extractArtifactContent(result.text, output, isSingle);\n\t\t\t\tif (content) {\n\t\t\t\t\tlog.debug(`Extracted artifact: ${output}`, { featureId, agent: step.agent });\n\t\t\t\t\tawait store.writeArtifact(featureId, output as ArtifactName, content);\n\t\t\t\t} else {\n\t\t\t\t\tlog.warn(`Failed to extract artifact: ${output}`, { featureId, agent: step.agent });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tlog.info(`Agent completed: ${step.agent}:${step.action}`, { featureId });\n\t} finally {\n\t\t// 12. Agent release callback\n\t\tcontext.onAgentFinished?.();\n\t}\n};\n"]}