@bridge_gpt/mcp-server 0.1.14 → 0.1.16

package/build/index.js

@@ -23,6 +23,8 @@ import { VERSION } from "./version.generated.js";
 import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
+import { runStartTicketsCli } from "./start-tickets.js";
+import { runDoctorCli } from "./doctor.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
 import { runPipeline, resumePipeline, listPipelineRuns, deletePipelineRun, } from "./pipeline-orchestrator.js";
@@ -610,41 +612,54 @@ body explicitly says to serialize structured output.
     }
 }
 // ---------------------------------------------------------------------------
-// CLI: --init
+// CLI subcommand dispatch
 // ---------------------------------------------------------------------------
-if (process.argv.includes("--init")) {
+//
+// `--init`, `--upgrade`, and the positional `start-tickets` subcommand are all
+// routed through a single ``dispatchCliSubcommand`` guard that runs and exits
+// BEFORE the MCP server is constructed and connected. This keeps the single
+// existing ``bridge-api-mcp-server`` bin and leaves a clean seam for future
+// subcommands.
+/**
+ * Ensure a ``package.json`` exists in ``cwd`` for CLI commands that scaffold
+ * into a project. Returns ``null`` on success, or the exact user-facing error
+ * string (preserved verbatim from the previous standalone guards).
+ */
+async function ensurePackageJsonForCliCommand(flagName, cwd) {
     try {
-        await stat(path.join(process.cwd(), "package.json"));
+        await stat(path.join(cwd, "package.json"));
+        return null;
     }
     catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--init must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+        return ("Error: No package.json found in current directory.\n" +
+            `${flagName} must be run from your project root (the directory containing package.json).`);
+    }
+}
+/** Run the ``--init`` scaffolding flow. Returns a process exit code. */
+async function runInitCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--init", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        await runInit(process.cwd());
-        process.exit(0);
+        await runInit(cwd);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --init failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
-// ---------------------------------------------------------------------------
-// CLI: --upgrade
-// ---------------------------------------------------------------------------
-if (process.argv.includes("--upgrade")) {
-    try {
-        await stat(path.join(process.cwd(), "package.json"));
-    }
-    catch {
-        console.error("Error: No package.json found in current directory.\n" +
-            "--upgrade must be run from your project root (the directory containing package.json).");
-        process.exit(1);
+/** Run the ``--upgrade`` flow (npm install latest + re-scaffold). */
+async function runUpgradeCli(cwd) {
+    const guardError = await ensurePackageJsonForCliCommand("--upgrade", cwd);
+    if (guardError) {
+        console.error(guardError);
+        return 1;
     }
     try {
-        const cwd = process.cwd();
         const oldVersion = VERSION;
         console.log("Upgrading @bridge_gpt/mcp-server to latest...\n");
         execSync("npm i @bridge_gpt/mcp-server@latest", { stdio: "inherit" });
@@ -660,14 +675,52 @@ if (process.argv.includes("--upgrade")) {
         console.log("\nRefreshing scaffolded artifacts...\n");
         await runInit(cwd);
         console.log("\nUpgrade complete.");
-        process.exit(0);
+        return 0;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`Bridge API --upgrade failed: ${msg}`);
-        process.exit(1);
+        return 1;
     }
 }
+/**
+ * Route CLI subcommands before MCP server startup. Returns an exit code to
+ * exit the process with, or ``null`` to continue to normal MCP server startup.
+ *
+ * ``--init`` takes precedence over ``--upgrade`` (both are position-independent
+ * flags); ``start-tickets`` is a positional subcommand. Any other unknown,
+ * non-flag positional first token is rejected.
+ */
+async function dispatchCliSubcommand(argv) {
+    const cwd = process.cwd();
+    // A positional subcommand owns the rest of argv, so e.g. `start-tickets --init`
+    // is a start-tickets invocation, not an --init one. Check it before the
+    // position-independent --init / --upgrade flag guards.
+    if (argv[0] === "start-tickets") {
+        return runStartTicketsCli(argv.slice(1));
+    }
+    // The read-only `doctor` subcommand is routed beside start-tickets, before the
+    // flag guards and well before MCP server construction (it never starts the server).
+    if (argv[0] === "doctor") {
+        return runDoctorCli(argv.slice(1));
+    }
+    // --init takes precedence over --upgrade; both are position-independent flags.
+    if (argv.includes("--init")) {
+        return runInitCli(cwd);
+    }
+    if (argv.includes("--upgrade")) {
+        return runUpgradeCli(cwd);
+    }
+    if (argv.length > 0 && !argv[0].startsWith("-")) {
+        console.error(`Error: Unknown subcommand '${argv[0]}'. Run with --help for usage, or omit subcommands to start the MCP server.`);
+        return 1;
+    }
+    return null;
+}
+const cliExitCode = await dispatchCliSubcommand(process.argv.slice(2));
+if (cliExitCode !== null) {
+    process.exit(cliExitCode);
+}
 // ---------------------------------------------------------------------------
 // Server
 // ---------------------------------------------------------------------------
@@ -849,7 +902,8 @@ registerTool("get_tickets", {
 registerTool("get_ticket", {
     description: "Retrieve full details for a single Jira ticket by its key. " +
         "Returns summary, status, type, assignee, reporter, description, and timestamps. " +
-        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets.",
+        "All data is fetched live from Jira. Use get_tickets to search/list multiple tickets. " +
+        "Use get_comments to fetch comments on the ticket.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -861,6 +915,23 @@ registerTool("get_ticket", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
+registerTool("get_comments", {
+    description: "Retrieve all comments on a Jira ticket, oldest-first. " +
+        "Returns an array of {id, author, body, created, updated}. " +
+        "Comment bodies are Markdown (converted from Jira wiki markup). " +
+        "Use this to read what a developer or stakeholder has said on a ticket. " +
+        "Use add_comment to post a new comment.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123)"),
+    },
+}, async ({ ticket_number }) => {
+    const url = buildGetUrl(`/tickets/${encodeURIComponent(ticket_number)}/comments`, { repo_name: REPO_NAME });
+    const resp = await fetch(url, { headers: GET_HEADERS });
+    const text = await handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+});
 registerTool("create_ticket", {
     description: "Create a new Jira ticket in the configured project. Requires either description or file_path (or both — file_path takes precedence). " +
         "Returns JSON with {ticket_key: 'PROJ-123', url: 'https://...'}. " +
@@ -1971,6 +2042,8 @@ const VALID_CONFIG_FIELDS = [
     "template_correctness_standards", "style_correctness_standards",
     "design_principles",
     "post_pr_target_status", "ci_check_config", "ci_followup_config",
+    "allow_mutating_smoke_ops",
+    "selected_mcp_slugs",
 ].join(", ");
 registerTool("list_config_fields", {
     description: "List all configurable fields available for reading and updating via the Bridge API. " +
@@ -2016,18 +2089,101 @@ registerTool("update_config_field", {
         "Returns 400 if the field name is invalid, 404 if the repository has no configuration row yet.",
     inputSchema: {
         field_name: z.string().describe(`The configuration field to update. Valid options: ${VALID_CONFIG_FIELDS}`),
-        value: z.string().optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
-            "Omit both value and file_path to set the field to NULL (clearing it)."),
+        value: z.union([z.string(), z.boolean(), z.array(z.string())]).optional().describe("The new value for the configuration field. Provide either value or file_path, not both. " +
+            "Most fields take a string; scalar boolean fields (e.g. allow_mutating_smoke_ops) take true/false. " +
+            "The selected_mcp_slugs field takes a JSON array of supported MCP validation manual slug strings " +
+            "(e.g. [\"b2c-commerce-developer\", \"playwright-mcp\", \"pwa-kit-mcp\"]) — pass an array of strings, " +
+            "not a comma-delimited string; an empty array clears the selection. " +
+            "For string fields, omit both value and file_path to set the field to NULL (clearing it). " +
+            "Scalar boolean fields are NOT NULL and have no clear/null state: omitting the value writes false " +
+            "(matching the API-layer coercion), so pass true/false explicitly."),
         file_path: z.string().optional().describe("Path to a local file whose contents will be used as the new value. " +
             "Useful for large configuration values like detailed review instructions. " +
-            "The file must be UTF-8 encoded and under 1MB."),
+            "The file must be UTF-8 encoded and under 1MB. " +
+            "Not supported for scalar boolean fields like allow_mutating_smoke_ops."),
     },
 }, async ({ field_name, value, file_path }) => {
+    // JSONB array config fields (e.g. selected_mcp_slugs): forward the array value
+    // as JSON. Never join into a comma-delimited string — the backend expects a
+    // real JSON array and validates each slug against the mcp_docs allowlist.
+    const ARRAY_CONFIG_FIELDS = ["selected_mcp_slugs"];
+    if (ARRAY_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a JSON array field; file_path updates are not supported. Pass value as an array of slug strings.`,
+                        }),
+                    }],
+            };
+        }
+        // An omitted value clears the selection (empty array). Any defined value is
+        // forwarded verbatim as JSON so the backend can validate/reject it.
+        const arrayValue = value === undefined ? [] : value;
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: arrayValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
+    // Scalar boolean config fields: reject file-path updates and normalize boolean
+    // true/false and string "true"/"false" to a real boolean before persisting.
+    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops"];
+    if (BOOLEAN_CONFIG_FIELDS.includes(field_name)) {
+        if (file_path) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `'${field_name}' is a scalar boolean field; file_path updates are not supported. Pass value: true or value: false.`,
+                        }),
+                    }],
+            };
+        }
+        // NOT NULL boolean column: an omitted value writes false (no clear/null state),
+        // intentionally aligned with the API-layer coercion in update_config_field_endpoint.
+        let boolValue = false;
+        if (typeof value === "boolean") {
+            boolValue = value;
+        }
+        else if (typeof value === "string") {
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true") {
+                boolValue = true;
+            }
+            else if (normalized === "false" || normalized === "") {
+                boolValue = false;
+            }
+            else {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `Invalid value for '${field_name}': '${value}'. Expected true or false.`,
+                            }),
+                        }],
+                };
+            }
+        }
+        const resp = await fetch(buildUrl(`/config-field/${encodeURIComponent(field_name)}`), {
+            method: "PUT",
+            headers: POST_HEADERS,
+            body: JSON.stringify({ repo_name: REPO_NAME, value: boolValue }),
+        });
+        const text = await handleResponse(resp);
+        return { content: [{ type: "text", text }] };
+    }
     // Allow omitting both value and file_path to set NULL
     let finalValue = null;
     let note = "";
     if (value || file_path) {
-        const resolved = await resolveTextOrFile(value, file_path, "value");
+        const resolved = await resolveTextOrFile(typeof value === "string" ? value : undefined, file_path, "value");
         if (!resolved.ok)
             return resolved.errorResponse;
         finalValue = resolved.text;

package/build/pipelines.generated.js

@@ -511,7 +511,7 @@ export const INSTRUCTIONS = {
     "learn-documentation-instructions.md": "## Objective\n\nExplore the codebase to identify implementation documentation patterns — the markdown records that document what was built, why, and when — then draft `documentation_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Explore Implementation Record Patterns\n\nFocus on how the project records what was built, why, and when. These records serve as persistent project memory. Code-level documentation (docstrings, inline comments) is handled by correctness standards, not here.\n\n1. **Implementation Record Discovery**: Search for:\n   - Ticket-numbered documents matching `BAPI-*.md` or `PROJ-*.md` in `docs/` and subdirectories\n   - Feature/migration documents in `docs/`, `documentation/`, or similar directories\n   - Architecture Decision Records (ADRs) in `adr/`, `decisions/`, or similar\n   - Changelogs (`CHANGELOG.md`, release notes)\n\n   Count how many records exist and identify the naming convention.\n\n2. **Record Structure Analysis**: Read 3-5 representative implementation records (mix of early and recent). Document:\n   - Sections present (Summary, Architecture, Database Changes, API Reference, etc.)\n   - Level of detail provided\n   - Types of information captured (motivation, design decisions, schema changes, file paths, API contracts)\n   - How code examples and diagrams are used\n\n3. **Documentation Location and Organization**: Read the directory structure of `docs/` to identify where records are stored, the file naming convention, whether there is a table of contents or index, and whether subdirectories serve different purposes.\n\n### Phase 2 — Draft\n\nDraft `documentation_instructions` as clear, actionable instructions for an AI agent writing implementation documentation after completing a feature. Cover:\n- **Purpose**: Documents serve as persistent project memory for future agents and developers.\n- **When to write**: After completing any feature, refactor, migration, or significant bug fix.\n- **File naming convention**: Based on discovered patterns or sensible defaults.\n- **File location**: Where to place implementation records.\n- **Required sections**: Standard structure from analysis or sensible defaults.\n- **Content guidelines**: Level of detail — motivations, design decisions, database changes, file references, API contracts.\n- **Scope boundary**: Implementation records only; code-level docs belong in correctness standards.\n\nWrite the draft to `{docs_dir}/standards/documentation_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's implementation-record conventions (naming, location, required sections), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/documentation_instructions.md`.\n",
     "learn-e2e-testing.md": "## Objective\n\nDetect whether an E2E testing framework exists in the codebase, document how to run and write E2E tests, then draft `e2e_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Detect E2E Framework\n\nSearch for config files and indicators:\n- **Playwright**: Search for `playwright.config.ts`, `playwright.config.js`, `@playwright/test` in `package.json`\n- **Cypress**: Search for `cypress.json`, `cypress.config.*`, `cypress/` directory\n- **Selenium/WebDriver**: Search for `selenium` in `requirements.in` or `package.json`\n- **Puppeteer**: Search for `puppeteer` in `package.json`\n- **TestCafe**: Search for `.testcaferc.json`\n\nAlso read `package.json` for E2E-related scripts and search for test directories containing E2E tests.\n\nIf NO E2E testing framework is detected, write \"No E2E testing framework detected in this repository.\" to `{docs_dir}/standards/e2e_testing_instructions.md` and stop.\n\n### Phase 2 — Explore E2E Testing Conventions\n\n1. **Test Execution**: Read the E2E config file and `package.json` scripts to determine exact commands (all tests, single file, headed/headless), prerequisites (server running, database seeded), and environment requirements.\n\n2. **Test Patterns**: Read 2-3 representative E2E test files in `tests/playwright/` to identify structure (page objects, fixtures, helpers), login/auth flows, test data setup/teardown, async waiting strategies, and selector patterns.\n\n3. **Common Pitfalls**: Search for hard-coded waits (`setTimeout`, `page.waitForTimeout`), test isolation issues, and browser state management patterns across E2E test files.\n\n### Phase 3 — Draft\n\nDraft `e2e_testing_instructions` as clear, actionable instructions for an AI agent writing E2E tests. Cover:\n- How to run tests (exact commands, prerequisites)\n- Test structure and organization\n- Authentication and setup patterns\n- How to wait for async operations (never hard-coded sleeps)\n- Common pitfalls with browser automation\n- Guards against common AI weaknesses: flaky tests, brittle selectors, hard-coded waits\n\nWrite the draft to `{docs_dir}/standards/e2e_testing_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's E2E testing setup (framework detected, run commands, test patterns) — or state that no framework was detected — citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/e2e_testing_instructions.md`.\n",
     "learn-frontend-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for frontend code, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `frontend_correctness`\n- **Field name**: `frontend_correctness_standards`\n- **Scope**: JS, TS, JSX, TSX files: React/Vue/Angular/Svelte components, client-side logic, state management.\n\n## Instructions\n\n### Phase 1 — Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.js`, `**/*.ts`, `**/*.jsx`, `**/*.tsx` (excluding `node_modules/` and `build/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative frontend files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 — Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/frontend_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about frontend correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/frontend_correctness_standards.md`.\n",
-    "learn-review-instructions.md": "## Objective\n\nExplore the codebase to identify self-verification patterns, downstream impact analysis techniques, and local validation tooling, then draft `review_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Explore Self-Verification Patterns\n\nFocus on how an AI agent working in a code editor (with capabilities to search file contents by text pattern, search by filename pattern, read files, and call MCP tools) can verify its own code changes before requesting human review. Do NOT document test runners or CI/CD — focus on static analysis by reading code and searching for patterns.\n\n1. **Code Correctness Patterns**: Read 3-5 representative modules in `api/routes/` and `api/library/` to identify:\n   - Function signature conventions (return types, parameter patterns)\n   - Import conventions and layer boundaries (deprecated modules, import restrictions)\n   - Return value handling (structured results, tuple unpacking)\n   - Auth pattern compliance (required decorators, dependency injections, call order)\n   - Naming conventions (files, functions, classes, variables)\n   - Error handling patterns (try/except structure, ordering, logging)\n\n2. **Downstream Impact Analysis**: For each technique, demonstrate with a concrete codebase example:\n   - Caller discovery (text-pattern search for finding all callers of utility functions)\n   - Import graph analysis (finding all files importing from a module)\n   - Route registration verification (checking new routes are properly included)\n   - Database schema impact (finding queries referencing a given table/column)\n   - Model/schema usage (verifying model changes don't break dependents)\n\n3. **Local Validation Tooling**: Discover available MCP tools and validation capabilities:\n   - Database MCP tools (schema verification, query validation)\n   - Project API MCP tools (config verification, health checks)\n   - Hooks and guards (pre-commit hooks, pre-tool hooks)\n   - Safety model (read-only vs. mutating operations)\n\n4. **Correctness Standards Integration**: Read files in `{docs_dir}/standards/` matching `*_correctness_standards.md`. Extract key verification checkpoints that can be statically verified.\n\n### Phase 2 — Draft\n\nDraft `review_instructions` with these required sections:\n1. **Self-Verification Checklist** — Concise, scannable checklist with concrete actions and tools.\n2. **Local Code Verification** — Detailed static analysis instructions (function calls, imports, auth, error handling, naming).\n3. **Downstream Effect Analysis** — Finding callers, checking signature compatibility, import tracking, schema impact, route registration.\n4. **Validation Using Local Tooling** — Database validation, project API validation, hooks and guards.\n5. **Correctness Standards Reference** — Distilled checkpoints from loaded standards, or placeholder paths.\n6. **Common AI Agent Mistakes** — Verification-framed guards against duplication, unnecessary abstraction, data leaks, edge cases.\n\nWrite the draft to `{docs_dir}/standards/review_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's self-review and downstream-impact analysis patterns (verification checkpoints, local validation tooling), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/review_instructions.md`.\n",
+    "learn-review-instructions.md": "## Objective\n\nExplore the codebase to identify self-verification patterns, downstream impact analysis techniques, and local validation tooling, then draft `review_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Explore Self-Verification Patterns\n\nFocus on how an AI agent working in a code editor (with capabilities to search file contents by text pattern, search by filename pattern, read files, and call MCP tools) can verify its own code changes before requesting human review. Do NOT document test runners or CI/CD — focus on static analysis by reading code and searching for patterns.\n\n1. **Code Correctness Patterns**: Read 3-5 representative modules in `api/routes/` and `api/library/` to identify:\n   - Function signature conventions (return types, parameter patterns)\n   - Import conventions and layer boundaries (deprecated modules, import restrictions)\n   - Return value handling (structured results, tuple unpacking)\n   - Auth pattern compliance (required decorators, dependency injections, call order)\n   - Naming conventions (files, functions, classes, variables)\n   - Error handling patterns (try/except structure, ordering, logging)\n\n2. **Downstream Impact Analysis**: For each technique, demonstrate with a concrete codebase example:\n   - Caller discovery (text-pattern search for finding all callers of utility functions)\n   - Import graph analysis (finding all files importing from a module)\n   - Route registration verification (checking new routes are properly included)\n   - Database schema impact (finding queries referencing a given table/column)\n   - Model/schema usage (verifying model changes don't break dependents)\n\n3. **Local Validation Tooling**: Discover available MCP tools and validation capabilities:\n   - Database MCP tools (schema verification, query validation)\n   - Project API MCP tools (config verification, health checks)\n   - Hooks and guards (pre-commit hooks, pre-tool hooks)\n   - Safety model (read-only vs. mutating operations)\n   - Runtime smoke verification capability: Document which tools the executor can use to _run_ code safely (test runners, dbhub MCP, local dev servers, fixture loaders) and whether mutations are permitted against local/ephemeral state. The per-repo `allow_mutating_smoke_ops` flag (on `config_code_repositories`) controls whether the final reviewer is allowed to plan mutating verification steps.\n\n4. **Correctness Standards Integration**: Read files in `{docs_dir}/standards/` matching `*_correctness_standards.md`. Extract key verification checkpoints that can be statically verified.\n\n### Phase 2 — Draft\n\nDraft `review_instructions` with these required sections:\n1. **Self-Verification Checklist** — Concise, scannable checklist with concrete actions and tools.\n2. **Local Code Verification** — Detailed static analysis instructions (function calls, imports, auth, error handling, naming).\n3. **Downstream Effect Analysis** — Finding callers, checking signature compatibility, import tracking, schema impact, route registration.\n4. **Validation Using Local Tooling** — Database validation, project API validation, hooks and guards.\n5. **Correctness Standards Reference** — Distilled checkpoints from loaded standards, or placeholder paths.\n6. **Common AI Agent Mistakes** — Verification-framed guards against duplication, unnecessary abstraction, data leaks, edge cases.\n\nWrite the draft to `{docs_dir}/standards/review_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's self-review and downstream-impact analysis patterns (verification checkpoints, local validation tooling), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/review_instructions.md`.\n",
     "learn-style-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for style files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `style_correctness`\n- **Field name**: `style_correctness_standards`\n- **Scope**: Style files: CSS, SCSS, SASS, LESS, Styled Components, Tailwind configs.\n\n## Instructions\n\n### Phase 1 — Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.css`, `**/*.scss`, `**/*.sass`, `**/*.less` (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative style files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 — Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/style_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about style-file correctness conventions (structure, naming, methodology), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/style_correctness_standards.md`.\n",
     "learn-template-correctness.md": "## Objective\n\nExplore the codebase to identify correctness standards for template files, then draft the corresponding correctness standards document.\n\n## Target Type\n\n- **Type**: `template_correctness`\n- **Field name**: `template_correctness_standards`\n- **Scope**: Template files: HTML, Jinja2, Handlebars, EJS, ERB, Blade, Pug, Twig.\n\n## Instructions\n\n### Phase 1 — Explore Correctness Patterns\n\nFocus on implementation correctness: how to write code that is correct, idiomatic, and robust within this project's conventions.\n\n1. **File Type Detection**: Search by filename pattern for files matching `**/*.html`, `**/*.jinja2`, `**/*.j2` in `templates/` and similar directories (excluding `node_modules/`). If very few or no files exist, note this and draft minimal instructions.\n\n2. **Convention Analysis**: Read 3-5 representative template files to identify:\n   - Structure patterns (imports, exports, class structure, function ordering)\n   - Naming conventions (variables, functions, classes, files)\n   - Framework conventions and idioms\n   - Best practices followed\n   - Issues and inconsistencies\n\n### Phase 2 — Draft\n\nDraft correctness standards as clear, actionable instructions for an AI code generation agent. Cover:\n- Code structure and organization requirements\n- Naming conventions to follow\n- Framework-specific patterns and idioms\n- Security requirements relevant to this code type\n- Performance considerations\n- Common mistakes to avoid\n- Guards against common AI weaknesses: duplicative code, verbose implementations, security vulnerabilities\n\nWrite the draft to `{docs_dir}/standards/template_correctness_standards.md`.\n\n## Return\n\nReturn a brief summary of what was learned about template-file correctness conventions (structure, naming, framework idioms), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/template_correctness_standards.md`.\n",
     "learn-unit-testing.md": "## Objective\n\nExplore the codebase to identify the test runner, assertion library, mocking framework, and testing patterns, then draft `unit_testing_instructions` for the project config.\n\n## Instructions\n\n### Phase 1 — Explore Testing Infrastructure\n\n1. **Test Runner and Framework Detection**: Search for test runner configs (`pytest.ini`, `pyproject.toml` `[tool.pytest]` section, `jest.config.*`) and read `package.json` test scripts. Read the `tests/` directory structure.\n\n2. **Testing Patterns**: Read 3-5 representative test files in `tests/pytest/` to identify:\n   - Assertion library and style (`assert`, `expect`, custom matchers)\n   - Mocking framework (`unittest.mock`, `jest.mock`, `sinon`, etc.)\n   - Fixture patterns (setup/teardown)\n   - Test organization (by module, feature, layer)\n   - Exemplary tests vs. weak tests\n\n3. **How to Run Tests**: Read `pyproject.toml`, `package.json`, and `Makefile` (if present) to determine exact commands for: full suite, single file, by name pattern, with verbose output.\n\n4. **Mocking vs. Fidelity**: Read test helper files in `tests/pytest/helpers/` to document how external APIs are mocked, whether integration tests exist alongside unit tests, and patterns for avoiding third-party calls in tests.\n\n### Phase 2 — Draft\n\nDraft `unit_testing_instructions` as clear, actionable instructions for an AI agent writing unit tests. Cover:\n- How to run tests (exact commands)\n- Which test framework and assertion library to use\n- How to mock external dependencies without calling third parties\n- How to structure test files and test functions\n- What constitutes a thorough test (not just happy path)\n- How to avoid shallow tests that pass but don't verify meaningful behavior\n- Guards against common AI weaknesses: tests that mock the thing being tested, trivially passing assertions, overly complex setup\n\nWrite the draft to `{docs_dir}/standards/unit_testing_instructions.md`.\n\n## Return\n\nReturn a brief summary of what was learned about the project's unit testing setup (test runner, assertion library, mocking framework, run commands), citing the key files inspected, and confirm the draft was written to `{docs_dir}/standards/unit_testing_instructions.md`.\n",