feat(qa): gate pipeline and wire auto QA creation

Author: Velhron

.docker/docker-entrypoint.sh

@@ -4,7 +4,7 @@
 # pass over a host projects directory can make startup appear hung.
 if [ "$(id -u)" = "0" ]; then
   install -d -o node -g node /data /home/node/.claude /home/node/.codex 2>/dev/null || true
-  chown -R node:node /data /home/node/.claude /home/node/.codex 2>/dev/null || true
+  chown -R node:node /data /home/node/.claude /home/node/.codex /home/node/.npm 2>/dev/null || true
   if [ -e /home/node/.claude.json ]; then
     chown node:node /home/node/.claude.json 2>/dev/null || true
   fi

.env.example

@@ -242,6 +242,14 @@ LOG_LEVEL=debug
 # Enable only for runtimes/transports that advertise session fork support.
 # AIF_WARMUP_ENABLED=false
 
+# ----------------------------------------------------------
+# QA pipeline feature toggle (master switch)
+# ----------------------------------------------------------
+# Default false. When false the manual POST /tasks/:id/run-qa endpoint returns
+# 403 and the autoQa auto-trigger on approve_done is skipped. Enable to run the
+# /aif-qa --all pipeline (change-summary -> test-plan -> test-cases) for tasks.
+# AIF_QA_PIPELINE_ENABLED=false
+
 # ----------------------------------------------------------
 # Codex OAuth login in Docker (dev-only broker)
 # ----------------------------------------------------------

docs/api.md

@@ -761,7 +761,9 @@ runner generates three markdown artifacts under `<paths.qa>/<branch-slug>/`
 (`change-summary.md`, `test-plan.md`, `test-cases.md`), persists them onto the task
 (`qaChangeSummary`, `qaTestPlan`, `qaTestCases`), and updates `qaStatus`. Execution
 uses the task's worktree root when present (`worktreePath`), otherwise the project
-root. The same pipeline runs automatically after `approve_done` when `autoQa = true`.
+root. Artifact slugs use the task's persisted `branchName` when present; branchless
+tasks fall back to the current git branch in the execution root. The same pipeline
+runs automatically after `approve_done` when `autoQa = true`.
 
 **Response:** `202 Accepted`
 
@@ -771,10 +773,10 @@ root. The same pipeline runs automatically after `approve_done` when `autoQa = t
 
 **Errors:**
 
+- `403` — QA pipeline feature flag is disabled (`AIF_QA_PIPELINE_ENABLED=false`); body carries `code: "feature_disabled"`
 - `404` — task not found
 - `404` — project not found
 - `409` — QA is already running (`qaStatus === "running"`)
-- `409` — task has no `branchName` (required to compute the artifact slug)
 
 **WebSocket events:** `task:qa_started` immediately, then `task:qa_done` or
 `task:qa_failed` when the run finishes. The runner also broadcasts `task:updated`

docs/configuration.md

@@ -65,6 +65,7 @@ Node packages (`@aif/api`, `@aif/agent`, `@aif/data`, `@aif/shared`) auto-load e
 | `AGENT_CHAT_MAX_TURNS`                                 | number  | `50`                           | Maximum turns (tool calls) per chat session before the runtime terminates. Increase for complex multi-file tasks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `AIF_USAGE_LIMITS_ENABLED`                             | boolean | `false`                        | Master switch for the usage-limits feature. When `false` (default): `/runtime-profiles` skips Codex indexed-head overlay refresh and the Claude provider-identity lookup; the runtime service skips `observeRuntimeLimitEvent` / `extractLatestRuntimeLimitSnapshot` / `extractRuntimeLimitSnapshotFromError` during every runtime run; the WebSocket `project:runtime_limit_updated` broadcast is suppressed; the agent's stage error handler does not persist `limitSnapshot` onto tasks; the chat API omits `runtimeLimitSnapshot` from responses; and the web UI hides all 5 usage-limit surfaces (USAGE button in Header, TaskCard badge, TaskDetailHeader badge, ProjectRuntimeSettings "Recent Limit Signals", Chat active-limit banner + `CHAT_USAGE_LIMIT` fallback). Persisted snapshots already in the DB are still returned on read but never updated. When `true`, Codex overlays and broadcasts are fed from the background SQLite index (`codex_limit_heads`/`codex_limit_history`) instead of request-path filesystem scans. Set to `true` only when you actively monitor rate-limit windows |
 | `AIF_WARMUP_ENABLED`                                   | boolean | `false`                        | Master switch for project runtime warmup. When `false`, `/projects/:id/warmup` reports `enabled=false`, create requests return `403`, and the web UI hides Warmup entry points. When `true`, supported planner, implementer, and review runtimes can create time-limited seed sessions that later matching stage runs may fork. Warmup lifecycle logs use the `projects-route`, `api-runtime`, and runtime adapter log components and include project/runtime ids, TTL, expiry, and status without prompt text or secrets                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `AIF_QA_PIPELINE_ENABLED`                              | boolean | `false`                        | Master switch for the task QA pipeline. When `false` (default): the manual `POST /tasks/:id/run-qa` endpoint returns `403` with `code: "feature_disabled"`, and the `autoQa` auto-trigger on `approve_done` is skipped. When `true`, manual runs and `autoQa` tasks execute the `/aif-qa --all` pipeline (change-summary → test-plan → test-cases) via `runApiRuntimeOneShot` and persist the three artifacts on the task                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `AIF_ENABLE_CODEX_LOGIN_PROXY`                         | boolean | `false`                        | Enable the in-container Codex OAuth login broker and the api-side `/auth/codex/*` proxy. Dev-only. In production prefer `OPENAI_API_KEY`. See [Providers](providers.md#codex-oauth-login-in-docker-broker)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `AIF_CODEX_LOGIN_BROKER_PORT`                          | number  | `3010`                         | Port the Codex login broker binds inside the agent container (not mapped to the host by the dev compose)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `AGENT_INTERNAL_URL`                                   | string  | `http://agent:3010`            | Base URL the api uses to reach the agent-side Codex login broker over the docker network                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

packages/agent/src/__tests__/hooks.test.ts

@@ -70,6 +70,7 @@ function makeEnv(overrides: Record<string, unknown> = {}) {
     AIF_USAGE_LIMITS_ENABLED: false,
     AIF_STAGE_RUNTIME_PIN_ENABLED: false,
     AIF_WARMUP_ENABLED: false,
+    AIF_QA_PIPELINE_ENABLED: false,
     AIF_RUNTIME_CODEX_NATIVE_SUBAGENTS_ENABLED: false,
     AIF_TASK_WORKTREES_ENABLED: false,
     AIF_RUNTIME_SESSION_FORK_ENABLED: false,

packages/api/src/__tests__/qaRunner.test.ts

@@ -91,12 +91,15 @@ describe("runQaQuery", () => {
     expect(mockRunApiRuntimeOneShot).not.toHaveBeenCalled();
   });
 
-  it("fails loud when task has no branchName (does not guess via git)", async () => {
+  it("falls back to the current git branch when task has no branchName", async () => {
     mockFindTaskById.mockReturnValue({ id: "t1", branchName: null, qaStatus: "idle" });
+    // executionRoot is a plain tmpdir (no git work tree), so the skill-mirrored
+    // `git branch --show-current` fallback resolves to "" → the "branch" slug.
+    const slug = computeQaBranchSlug("", root);
+    writeArtifacts(join(root, ".ai-factory/qa", slug));
     const res = await runQaQuery({ projectId: "p1", taskId: "t1", executionRoot: root });
-    expect(res.ok).toBe(false);
-    expect(res.error).toMatch(/branchName/);
-    expect(mockRunApiRuntimeOneShot).not.toHaveBeenCalled();
+    expect(res.ok).toBe(true);
+    expect(mockRunApiRuntimeOneShot).toHaveBeenCalled();
   });
 
   it("calls runtime with qa workflow contract", async () => {

packages/api/src/__tests__/runQaRoute.test.ts

@@ -1,8 +1,13 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { Hono } from "hono";
-import { projects, tasks } from "@aif/shared";
+import { projects, tasks, resetEnvCache } from "@aif/shared";
 import { createTestDb } from "@aif/shared/server";
 
+// QA routes are gated behind AIF_QA_PIPELINE_ENABLED (off by default). Enable it
+// before importing the route module — schemas.ts calls getEnv() at schema-definition
+// time, which caches the parsed env. The disabled-flag case below toggles it back.
+process.env.AIF_QA_PIPELINE_ENABLED = "true";
+
 const testDb = { current: createTestDb() };
 
 vi.mock("@aif/shared/server", async (importOriginal) => {
@@ -79,11 +84,16 @@ describe("POST /tasks/:id/run-qa", () => {
     expect(mockRunQaQuery).not.toHaveBeenCalled();
   });
 
-  it("returns 409 when task has no branchName", async () => {
+  it("returns 202 for a branchless task (runner resolves the branch via git)", async () => {
     seedTask({ branchName: null });
     const res = await app.request("/tasks/t1/run-qa", { method: "POST" });
-    expect(res.status).toBe(409);
-    expect(mockRunQaQuery).not.toHaveBeenCalled();
+    expect(res.status).toBe(202);
+    await new Promise((r) => setTimeout(r, 0));
+    expect(mockRunQaQuery).toHaveBeenCalledWith({
+      projectId: "p1",
+      taskId: "t1",
+      executionRoot: "/tmp/p1",
+    });
   });
 
   it("returns 202 and triggers the runner on a valid request", async () => {
@@ -110,4 +120,20 @@ describe("POST /tasks/:id/run-qa", () => {
       executionRoot: "/tmp/wt/t1",
     });
   });
+
+  it("returns 403 with feature_disabled when AIF_QA_PIPELINE_ENABLED is off", async () => {
+    seedTask();
+    process.env.AIF_QA_PIPELINE_ENABLED = "false";
+    resetEnvCache();
+    try {
+      const res = await app.request("/tasks/t1/run-qa", { method: "POST" });
+      expect(res.status).toBe(403);
+      const body = (await res.json()) as { code?: string };
+      expect(body.code).toBe("feature_disabled");
+      expect(mockRunQaQuery).not.toHaveBeenCalled();
+    } finally {
+      process.env.AIF_QA_PIPELINE_ENABLED = "true";
+      resetEnvCache();
+    }
+  });
 });

packages/api/src/__tests__/settings.test.ts

@@ -1,8 +1,9 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { Hono } from "hono";
 import { mkdirSync, mkdtempSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { resetEnvCache } from "@aif/shared";
 
 // Create a temp dir to act as monorepo root and home
 const tempRoot = mkdtempSync(join(tmpdir(), "settings-test-"));
@@ -107,6 +108,7 @@ vi.mock("@aif/data", () => ({
   isRuntimeProfileEligibleForAppDefaults: (runtimeProfileId: string | null) =>
     runtimeProfileId == null || eligibleAppDefaultProfileIds.has(runtimeProfileId),
   createDbUsageSink: () => ({ record: vi.fn() }),
+  listRuntimeProfiles: () => [],
 }));
 
 vi.mock("node:os", async (importOriginal) => {
@@ -117,7 +119,7 @@ vi.mock("node:os", async (importOriginal) => {
   };
 });
 
-const { settingsRoutes } = await import("../routes/settings.js");
+const { settingsRoutes, buildSettingsOverview } = await import("../routes/settings.js");
 
 function createApp() {
   const app = new Hono();
@@ -514,3 +516,30 @@ describe("settings API — config routes", () => {
     });
   });
 });
+
+describe("settings overview — QA pipeline flag", () => {
+  const original = process.env.AIF_QA_PIPELINE_ENABLED;
+
+  afterEach(() => {
+    if (original === undefined) {
+      delete process.env.AIF_QA_PIPELINE_ENABLED;
+    } else {
+      process.env.AIF_QA_PIPELINE_ENABLED = original;
+    }
+    resetEnvCache();
+  });
+
+  it("reports qaPipelineEnabled: true when AIF_QA_PIPELINE_ENABLED is on", async () => {
+    process.env.AIF_QA_PIPELINE_ENABLED = "true";
+    resetEnvCache();
+    const overview = await buildSettingsOverview();
+    expect(overview.qaPipelineEnabled).toBe(true);
+  });
+
+  it("reports qaPipelineEnabled: false when AIF_QA_PIPELINE_ENABLED is off", async () => {
+    process.env.AIF_QA_PIPELINE_ENABLED = "false";
+    resetEnvCache();
+    const overview = await buildSettingsOverview();
+    expect(overview.qaPipelineEnabled).toBe(false);
+  });
+});

packages/api/src/__tests__/tasks.test.ts

@@ -460,6 +460,37 @@ describe("tasks API", () => {
       expect(body.useSubagents).toBe(false);
     });
 
+    it("should persist autoQa from create payload", async () => {
+      const res = await app.request("/tasks", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          title: "Task with auto QA",
+          projectId: "test-project",
+          autoQa: true,
+        }),
+      });
+
+      expect(res.status).toBe(201);
+      const body = await res.json();
+      expect(body.autoQa).toBe(true);
+    });
+
+    it("should default autoQa to false when omitted on create", async () => {
+      const res = await app.request("/tasks", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          title: "Task without auto QA",
+          projectId: "test-project",
+        }),
+      });
+
+      expect(res.status).toBe(201);
+      const body = await res.json();
+      expect(body.autoQa).toBe(false);
+    });
+
     it("should default useSubagents to AGENT_USE_SUBAGENTS env value", async () => {
       const { getEnv } = await import("@aif/shared");
       const envDefault = getEnv().AGENT_USE_SUBAGENTS;

packages/api/src/routes/settings.ts

@@ -92,6 +92,7 @@ export async function buildSettingsOverview() {
       autoReviewStrategy: env.AGENT_AUTO_REVIEW_STRATEGY,
       usageLimitsEnabled: env.AIF_USAGE_LIMITS_ENABLED,
       warmupEnabled: env.AIF_WARMUP_ENABLED,
+      qaPipelineEnabled: env.AIF_QA_PIPELINE_ENABLED,
       runtimeReadiness: {
         availableRuntimeCount: registry.listRuntimes().length,
         runtimeProfileCount: runtimeProfiles.length,
@@ -114,6 +115,7 @@ export async function buildSettingsOverview() {
       autoReviewStrategy: env.AGENT_AUTO_REVIEW_STRATEGY,
       usageLimitsEnabled: env.AIF_USAGE_LIMITS_ENABLED,
       warmupEnabled: env.AIF_WARMUP_ENABLED,
+      qaPipelineEnabled: env.AIF_QA_PIPELINE_ENABLED,
       runtimeReadiness: {
         availableRuntimeCount: 0,
         runtimeProfileCount: allProfiles.length,