From 22507483b8de861b16f6bd6810adf331a362105b Mon Sep 17 00:00:00 2001
From: bgagent <bgagent@noreply.github.com>
Date: Wed, 17 Jun 2026 15:32:33 -0400
Subject: [PATCH] fix(jira): validate repo onboarding at map time (#369)

bgagent jira map (and linear onboard-project) accepted and persisted a
project->repo mapping for a repo with no active Blueprint. Every label
trigger then failed at task creation with 422 REPO_NOT_ONBOARDED, with no
visible operator feedback.

Add a shared checkRepoOnboarding helper (cli/src/repo-onboarding.ts) that
reads the RepoTable via the RepoTableName stack output and reports whether
the repo has a status='active' row -- mirroring the runtime gate in
repo-config.ts. Both map commands now refuse (with actionable guidance) to
persist a mapping for a non-onboarded repo, unless --skip-onboarding-check
is passed. An inconclusive check (missing output / IAM gap) warns and
proceeds rather than blocking a valid mapping.

Linear's onboard-project gets the same guard since it shares the
create-task-core onboarding gate.

Docs: JIRA_SETUP_GUIDE.md and LINEAR_SETUP_GUIDE.md state the
Blueprint-onboarding prerequisite and document --skip-onboarding-check;
Starlight mirrors regenerated.

Tests: new repo-onboarding.test.ts plus map-guard cases in jira/linear
command tests (423 pass).
---
 cli/src/commands/jira.ts                      |  19 +++
 cli/src/commands/linear.ts                    |  19 +++
 cli/src/repo-onboarding.ts                    | 150 ++++++++++++++++++
 cli/test/commands/jira.test.ts                |  70 +++++++-
 cli/test/commands/linear.test.ts              |  93 ++++++++++-
 cli/test/repo-onboarding.test.ts              | 125 +++++++++++++++
 docs/guides/JIRA_SETUP_GUIDE.md               |   6 +
 docs/guides/LINEAR_SETUP_GUIDE.md             |   7 +-
 .../content/docs/using/Jira-setup-guide.md    |   6 +
 .../content/docs/using/Linear-setup-guide.md  |   7 +-
 10 files changed, 494 insertions(+), 8 deletions(-)
 create mode 100644 cli/src/repo-onboarding.ts
 create mode 100644 cli/test/repo-onboarding.test.ts

diff --git a/cli/src/commands/jira.ts b/cli/src/commands/jira.ts
index 46e799fa..3b4139c1 100644
--- a/cli/src/commands/jira.ts
+++ b/cli/src/commands/jira.ts
@@ -44,6 +44,7 @@ import {
   StoredJiraOauthToken,
 } from '../jira-oauth';
 import { awaitOauthCallback, CALLBACK_URL } from '../oauth-callback-server';
+import { checkRepoOnboarding, notOnboardedGuidance } from '../repo-onboarding';
 
 /** Default label that triggers an ABCA task when applied to a Jira issue. */
 const DEFAULT_LABEL_FILTER = 'bgagent';
@@ -652,6 +653,7 @@ export function makeJiraCommand(): Command {
       .option('--label <label>', `Label that triggers a task (default: ${DEFAULT_LABEL_FILTER})`, DEFAULT_LABEL_FILTER)
       .option('--region <region>', 'AWS region (defaults to configured region)')
       .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
+      .option('--skip-onboarding-check', 'Persist the mapping even if the repo has no active Blueprint (the mapping cannot trigger until one is deployed)')
       .action(async (cloudId: string, projectKey: string, opts) => {
         const config = loadConfig();
         const region = opts.region || config.region;
@@ -673,6 +675,23 @@ export function makeJiraCommand(): Command {
           process.exit(1);
         }
 
+        // Onboarding gate: refuse to persist a mapping for a repo that has
+        // no active Blueprint, since every label trigger would fail at
+        // task-creation with 422 REPO_NOT_ONBOARDED — and the failure is
+        // nearly invisible to the operator. An inconclusive check (no
+        // RepoTable output, IAM gap) warns and proceeds rather than blocks.
+        if (!opts.skipOnboardingCheck) {
+          const onboarding = await checkRepoOnboarding({ region, stackName: opts.stackName, repo: opts.repo });
+          if (onboarding.kind === 'not-onboarded') {
+            for (const line of notOnboardedGuidance(opts.repo, onboarding)) {
+              console.error(line);
+            }
+            process.exit(1);
+          } else if (onboarding.kind === 'unverifiable') {
+            console.error(`⚠ Could not verify repo onboarding (${onboarding.detail}); proceeding without the check.`);
+          }
+        }
+
         const now = new Date().toISOString();
         const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({ region }));
         await ddb.send(new PutCommand({
diff --git a/cli/src/commands/linear.ts b/cli/src/commands/linear.ts
index 475dbebe..fb3367d3 100644
--- a/cli/src/commands/linear.ts
+++ b/cli/src/commands/linear.ts
@@ -45,6 +45,7 @@ import {
   StoredLinearOauthToken,
 } from '../linear-oauth';
 import { awaitOauthCallback, CALLBACK_URL } from '../oauth-callback-server';
+import { checkRepoOnboarding, notOnboardedGuidance } from '../repo-onboarding';
 
 /** Default label that triggers an ABCA task when applied to a Linear issue. */
 const DEFAULT_LABEL_FILTER = 'bgagent';
@@ -1314,6 +1315,7 @@ export function makeLinearCommand(): Command {
       .option('--team-id <id>', 'Optional Linear team UUID for the project (stored for debug)')
       .option('--region <region>', 'AWS region (defaults to configured region)')
       .option('--stack-name <name>', 'CloudFormation stack name', 'backgroundagent-dev')
+      .option('--skip-onboarding-check', 'Persist the mapping even if the repo has no active Blueprint (the mapping cannot trigger until one is deployed)')
       .action(async (projectId: string, opts) => {
         const config = loadConfig();
         const region = opts.region || config.region;
@@ -1341,6 +1343,23 @@ export function makeLinearCommand(): Command {
           process.exit(1);
         }
 
+        // Onboarding gate: refuse to persist a mapping for a repo that has
+        // no active Blueprint, since every label trigger would fail at
+        // task-creation with 422 REPO_NOT_ONBOARDED (Linear shares the same
+        // create-task-core gate as Jira). An inconclusive check warns and
+        // proceeds rather than blocks.
+        if (!opts.skipOnboardingCheck) {
+          const onboarding = await checkRepoOnboarding({ region, stackName: opts.stackName, repo: opts.repo });
+          if (onboarding.kind === 'not-onboarded') {
+            for (const line of notOnboardedGuidance(opts.repo, onboarding)) {
+              console.error(line);
+            }
+            process.exit(1);
+          } else if (onboarding.kind === 'unverifiable') {
+            console.error(`⚠ Could not verify repo onboarding (${onboarding.detail}); proceeding without the check.`);
+          }
+        }
+
         const now = new Date().toISOString();
         const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({ region }));
         await ddb.send(new PutCommand({
diff --git a/cli/src/repo-onboarding.ts b/cli/src/repo-onboarding.ts
new file mode 100644
index 00000000..bcdb38dd
--- /dev/null
+++ b/cli/src/repo-onboarding.ts
@@ -0,0 +1,150 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { CloudFormationClient, DescribeStacksCommand } from '@aws-sdk/client-cloudformation';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Stack-output key that exposes the name of the RepoTable — the DynamoDB
+ * table the Blueprint construct writes a `status='active'` row into for
+ * every onboarded repository. Mirrors the `CfnOutput` id in
+ * `cdk/src/stacks/agent.ts`.
+ */
+export const REPO_TABLE_OUTPUT_KEY = 'RepoTableName';
+
+/**
+ * Result of checking whether a repo has a deployed Blueprint (i.e. an
+ * active RepoTable row). Mirrors the runtime onboarding gate in
+ * `cdk/src/handlers/shared/repo-config.ts` (`lookupRepo`):
+ *
+ *   - `onboarded`   — an `active` row exists; the repo will trigger.
+ *   - `not-onboarded` (`missing`)  — no row at all for this `owner/repo`.
+ *   - `not-onboarded` (`inactive`) — a row exists but `status != 'active'`
+ *     (e.g. soft-removed); the runtime gate treats this as not onboarded.
+ *   - `unverifiable` — the check could not run (RepoTable output absent, or
+ *     an IAM / read error). The caller should warn and proceed rather than
+ *     block on an inconclusive signal, since the misconfiguration is the
+ *     check's, not the mapping's.
+ */
+export type RepoOnboardingResult =
+  | { readonly kind: 'onboarded' }
+  | { readonly kind: 'not-onboarded'; readonly reason: 'missing' | 'inactive'; readonly status?: string }
+  | { readonly kind: 'unverifiable'; readonly detail: string };
+
+export interface CheckRepoOnboardingOptions {
+  readonly region: string;
+  readonly stackName: string;
+  /** The `owner/repo` string the operator is about to map. */
+  readonly repo: string;
+}
+
+/**
+ * Read a single stack output. Returns null when the stack or the output
+ * does not exist, so callers can distinguish "not deployed" from a real
+ * AWS error (which is rethrown).
+ */
+async function getStackOutput(region: string, stackName: string, outputKey: string): Promise<string | null> {
+  const cfn = new CloudFormationClient({ region });
+  try {
+    const result = await cfn.send(new DescribeStacksCommand({ StackName: stackName }));
+    const output = (result.Stacks?.[0]?.Outputs ?? []).find((o) => o.OutputKey === outputKey);
+    return output?.OutputValue ?? null;
+  } catch (err) {
+    const name = (err as Error)?.name ?? '';
+    const message = (err as Error)?.message ?? '';
+    if (name === 'ValidationError' && /does not exist/i.test(message)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Check whether `opts.repo` is onboarded — i.e. has an `active` row in the
+ * deployed RepoTable, the same condition the task-submit gate enforces at
+ * trigger time (`422 REPO_NOT_ONBOARDED`). Run this at `map`/`onboard`
+ * time so an operator learns immediately that a mapping can never fire,
+ * rather than discovering it deep in the processor when a label is added.
+ *
+ * Never throws for the "not onboarded" case — that is a normal verdict the
+ * caller turns into actionable guidance. A genuinely inconclusive check
+ * (missing output, IAM gap) returns `unverifiable` with detail so the
+ * caller can warn-and-proceed instead of falsely blocking a valid mapping.
+ */
+export async function checkRepoOnboarding(opts: CheckRepoOnboardingOptions): Promise<RepoOnboardingResult> {
+  let repoTableName: string | null;
+  try {
+    repoTableName = await getStackOutput(opts.region, opts.stackName, REPO_TABLE_OUTPUT_KEY);
+  } catch (err) {
+    return { kind: 'unverifiable', detail: `could not read stack outputs: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!repoTableName) {
+    return {
+      kind: 'unverifiable',
+      detail: `stack '${opts.stackName}' has no ${REPO_TABLE_OUTPUT_KEY} output (deploy the latest CDK stack to enable the onboarding check)`,
+    };
+  }
+
+  const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({ region: opts.region }));
+  let item: Record<string, unknown> | undefined;
+  try {
+    const result = await ddb.send(new GetCommand({
+      TableName: repoTableName,
+      Key: { repo: opts.repo },
+    }));
+    item = result.Item;
+  } catch (err) {
+    return { kind: 'unverifiable', detail: `could not read RepoTable '${repoTableName}': ${err instanceof Error ? err.message : String(err)}` };
+  }
+
+  if (!item) {
+    return { kind: 'not-onboarded', reason: 'missing' };
+  }
+  const status = typeof item.status === 'string' ? item.status : undefined;
+  if (status !== 'active') {
+    return { kind: 'not-onboarded', reason: 'inactive', status };
+  }
+  return { kind: 'onboarded' };
+}
+
+/**
+ * Build the multi-line operator guidance printed when a repo is not
+ * onboarded. Shared by the Jira and Linear map commands so the remediation
+ * steps stay identical. `repo` is the offending `owner/repo`.
+ */
+export function notOnboardedGuidance(repo: string, result: Extract<RepoOnboardingResult, { kind: 'not-onboarded' }>): string[] {
+  const lead = result.reason === 'inactive'
+    ? `Repository '${repo}' has a RepoTable row but its status is '${result.status ?? 'unknown'}' (not 'active'), so the task-submit gate will reject every trigger with 422 REPO_NOT_ONBOARDED.`
+    : `Repository '${repo}' is not onboarded — it has no active Blueprint, so the task-submit gate will reject every trigger with 422 REPO_NOT_ONBOARDED.`;
+  return [
+    lead,
+    '',
+    'Onboard the repo first by deploying a Blueprint for it, then re-run this command:',
+    '',
+    '  1. Add (or point) a Blueprint construct at this repo in cdk/src/stacks/agent.ts,',
+    '     e.g. set BLUEPRINT_REPO / the `blueprintRepo` CDK context, or instantiate',
+    `       new Blueprint(this, 'MyRepoBlueprint', { repo: '${repo}', repoTable: repoTable.table });`,
+    '  2. Deploy:  MISE_EXPERIMENTAL=1 mise //cdk:deploy',
+    '  3. Re-run this map command.',
+    '',
+    'See docs/guides/QUICK_START.md (“Onboard a repository / Blueprint”) for the full steps.',
+    'To map anyway (e.g. you are deploying the Blueprint momentarily), pass --skip-onboarding-check.',
+  ];
+}
diff --git a/cli/test/commands/jira.test.ts b/cli/test/commands/jira.test.ts
index 96e69984..cdac6962 100644
--- a/cli/test/commands/jira.test.ts
+++ b/cli/test/commands/jira.test.ts
@@ -22,6 +22,7 @@ import {
   PutSecretValueCommand,
   ResourceExistsException,
 } from '@aws-sdk/client-secrets-manager';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
 import { ApiClient } from '../../src/api-client';
 import {
   isWebhookSecretConfigured,
@@ -365,9 +366,22 @@ describe('jira map action', () => {
   let exitSpy: jest.SpiedFunction<typeof process.exit>;
 
   beforeEach(() => {
-    ddbSend.mockReset().mockResolvedValue({});
+    // The `map` action issues a GetItem (onboarding check) then a PutItem
+    // (the mapping). Differentiate by command type: GetItem → an active
+    // RepoTable row (onboarded), PutItem → ack.
+    ddbSend.mockReset().mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) {
+        return Promise.resolve({ Item: { repo: 'owner/repo', status: 'active' } });
+      }
+      return Promise.resolve({});
+    });
     cfnSend.mockReset().mockResolvedValue({
-      Stacks: [{ Outputs: [{ OutputKey: 'JiraProjectMappingTableName', OutputValue: 'ProjMapTable' }] }],
+      Stacks: [{
+        Outputs: [
+          { OutputKey: 'JiraProjectMappingTableName', OutputValue: 'ProjMapTable' },
+          { OutputKey: 'RepoTableName', OutputValue: 'RepoTable' },
+        ],
+      }],
     });
     loadConfigSpy = jest.spyOn(config, 'loadConfig').mockReturnValue({ region: 'us-west-2' } as ReturnType<typeof config.loadConfig>);
     consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
@@ -390,10 +404,16 @@ describe('jira map action', () => {
     await program.parseAsync(['node', 'bgagent', 'map', ...args]);
   }
 
+  /** The PutCommand input from the mapping write (skips the GetItem check). */
+  function putMappingInput(): { TableName: string; Item: Record<string, unknown> } {
+    const call = ddbSend.mock.calls.find((c) => !(c[0] instanceof GetCommand));
+    if (!call) throw new Error('no PutCommand was issued');
+    return call[0].input;
+  }
+
   test('writes an active mapping row with the resolved label on the happy path', async () => {
     await runMap(['cloud-123', 'ENG', '--repo', 'owner/repo', '--label', 'agentme']);
-    expect(ddbSend).toHaveBeenCalledTimes(1);
-    const putInput = ddbSend.mock.calls[0][0].input;
+    const putInput = putMappingInput();
     expect(putInput.TableName).toBe('ProjMapTable');
     expect(putInput.Item).toMatchObject({
       jira_project_identity: 'cloud-123#ENG',
@@ -407,7 +427,7 @@ describe('jira map action', () => {
 
   test('defaults the trigger label to bgagent when --label is omitted', async () => {
     await runMap(['cloud-123', 'ENG', '--repo', 'owner/repo']);
-    expect(ddbSend.mock.calls[0][0].input.Item.label_filter).toBe('bgagent');
+    expect(putMappingInput().Item.label_filter).toBe('bgagent');
   });
 
   test('rejects an invalid --repo value before writing', async () => {
@@ -425,6 +445,46 @@ describe('jira map action', () => {
     await expect(runMap(['cloud-123', 'ENG', '--repo', 'owner/repo'])).rejects.toThrow('process.exit:1');
     expect(ddbSend).not.toHaveBeenCalled();
   });
+
+  test('rejects a repo with no RepoTable row (not onboarded) before writing the mapping', async () => {
+    ddbSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) return Promise.resolve({}); // no Item
+      return Promise.resolve({});
+    });
+    await expect(runMap(['cloud-123', 'ENG', '--repo', 'owner/repo'])).rejects.toThrow('process.exit:1');
+    // GetItem ran; no PutItem.
+    expect(ddbSend).toHaveBeenCalledTimes(1);
+    expect(ddbSend.mock.calls[0][0]).toBeInstanceOf(GetCommand);
+    expect(consoleErrorSpy.mock.calls.flat().join('\n')).toContain('REPO_NOT_ONBOARDED');
+  });
+
+  test('rejects a repo whose RepoTable row is not active (soft-removed)', async () => {
+    ddbSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) return Promise.resolve({ Item: { repo: 'owner/repo', status: 'removed' } });
+      return Promise.resolve({});
+    });
+    await expect(runMap(['cloud-123', 'ENG', '--repo', 'owner/repo'])).rejects.toThrow('process.exit:1');
+    expect(consoleErrorSpy.mock.calls.flat().join('\n')).toContain("status is 'removed'");
+  });
+
+  test('--skip-onboarding-check persists the mapping without a RepoTable read', async () => {
+    ddbSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) throw new Error('onboarding check should be skipped');
+      return Promise.resolve({});
+    });
+    await runMap(['cloud-123', 'ENG', '--repo', 'owner/repo', '--skip-onboarding-check']);
+    expect(ddbSend.mock.calls.some((c) => c[0] instanceof GetCommand)).toBe(false);
+    expect(putMappingInput().Item).toMatchObject({ repo: 'owner/repo', status: 'active' });
+  });
+
+  test('warns and proceeds when onboarding cannot be verified (no RepoTable output)', async () => {
+    cfnSend.mockResolvedValue({
+      Stacks: [{ Outputs: [{ OutputKey: 'JiraProjectMappingTableName', OutputValue: 'ProjMapTable' }] }],
+    });
+    await runMap(['cloud-123', 'ENG', '--repo', 'owner/repo']);
+    expect(consoleErrorSpy.mock.calls.flat().join('\n')).toContain('Could not verify repo onboarding');
+    expect(putMappingInput().Item).toMatchObject({ repo: 'owner/repo' });
+  });
 });
 
 describe('renderJiraAppTemplate', () => {
diff --git a/cli/test/commands/linear.test.ts b/cli/test/commands/linear.test.ts
index 610ac3f2..c780c129 100644
--- a/cli/test/commands/linear.test.ts
+++ b/cli/test/commands/linear.test.ts
@@ -17,13 +17,14 @@
  *  SOFTWARE.
  */
 
-import { PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { GetCommand, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
 import {
   autoLinkTokenOwner,
   findReusableOauthAppCredentials,
   generateInviteCode,
   INVITE_CODE_ALPHABET,
   isWebhookSecretConfigured,
+  makeLinearCommand,
   queryLinearTeamKeys,
   renderLinearAppTemplate,
 } from '../../src/commands/linear';
@@ -39,6 +40,16 @@ jest.mock('@aws-sdk/lib-dynamodb', () => {
   };
 });
 
+// CloudFormation — `getStackOutput` reads table names from here.
+const cfnSend = jest.fn();
+jest.mock('@aws-sdk/client-cloudformation', () => {
+  const actual = jest.requireActual('@aws-sdk/client-cloudformation');
+  return {
+    ...actual,
+    CloudFormationClient: jest.fn(() => ({ send: cfnSend })),
+  };
+});
+
 const ddbSend = jest.fn();
 
 // Build a fake JWT with a `sub` claim; the CLI only base64url-decodes the payload.
@@ -460,3 +471,83 @@ describe('queryLinearTeamKeys', () => {
     expect(await queryLinearTeamKeys('Bearer tok')).toEqual([]);
   });
 });
+
+describe('linear onboard-project onboarding guard', () => {
+  let loadConfigSpy: jest.SpiedFunction<typeof config.loadConfig>;
+  let consoleLogSpy: jest.SpiedFunction<typeof console.log>;
+  let consoleErrorSpy: jest.SpiedFunction<typeof console.error>;
+  let exitSpy: jest.SpiedFunction<typeof process.exit>;
+
+  // A valid full Linear project UUID (truncated URL UUIDs are rejected earlier).
+  const PROJECT_UUID = 'a680cae8-704c-4e64-92ac-0c80346d1aad';
+
+  beforeEach(() => {
+    ddbSend.mockReset().mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) {
+        return Promise.resolve({ Item: { repo: 'owner/repo', status: 'active' } });
+      }
+      return Promise.resolve({});
+    });
+    cfnSend.mockReset().mockResolvedValue({
+      Stacks: [{
+        Outputs: [
+          { OutputKey: 'LinearProjectMappingTableName', OutputValue: 'LinearProjMapTable' },
+          { OutputKey: 'RepoTableName', OutputValue: 'RepoTable' },
+        ],
+      }],
+    });
+    loadConfigSpy = jest.spyOn(config, 'loadConfig').mockReturnValue({ region: 'us-west-2' } as ReturnType<typeof config.loadConfig>);
+    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation();
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation();
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`process.exit:${code}`);
+    }) as never);
+  });
+
+  afterEach(() => {
+    loadConfigSpy.mockRestore();
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    exitSpy.mockRestore();
+  });
+
+  async function runOnboard(args: string[]): Promise<void> {
+    const program = makeLinearCommand();
+    await program.parseAsync(['node', 'bgagent', 'onboard-project', ...args]);
+  }
+
+  function putMappingInput(): { TableName: string; Item: Record<string, unknown> } {
+    const call = ddbSend.mock.calls.find((c) => !(c[0] instanceof GetCommand));
+    if (!call) throw new Error('no PutCommand was issued');
+    return call[0].input;
+  }
+
+  test('writes an active mapping on the happy path (onboarded repo)', async () => {
+    await runOnboard([PROJECT_UUID, '--repo', 'owner/repo']);
+    expect(putMappingInput().Item).toMatchObject({
+      linear_project_id: PROJECT_UUID,
+      repo: 'owner/repo',
+      status: 'active',
+    });
+  });
+
+  test('rejects a repo with no active Blueprint before writing', async () => {
+    ddbSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) return Promise.resolve({}); // no Item
+      return Promise.resolve({});
+    });
+    await expect(runOnboard([PROJECT_UUID, '--repo', 'owner/repo'])).rejects.toThrow('process.exit:1');
+    expect(ddbSend.mock.calls.some((c) => c[0] instanceof PutCommand)).toBe(false);
+    expect(consoleErrorSpy.mock.calls.flat().join('\n')).toContain('REPO_NOT_ONBOARDED');
+  });
+
+  test('--skip-onboarding-check bypasses the RepoTable read', async () => {
+    ddbSend.mockImplementation((cmd: unknown) => {
+      if (cmd instanceof GetCommand) throw new Error('onboarding check should be skipped');
+      return Promise.resolve({});
+    });
+    await runOnboard([PROJECT_UUID, '--repo', 'owner/repo', '--skip-onboarding-check']);
+    expect(ddbSend.mock.calls.some((c) => c[0] instanceof GetCommand)).toBe(false);
+    expect(putMappingInput().Item).toMatchObject({ repo: 'owner/repo', status: 'active' });
+  });
+});
diff --git a/cli/test/repo-onboarding.test.ts b/cli/test/repo-onboarding.test.ts
new file mode 100644
index 00000000..0981d44a
--- /dev/null
+++ b/cli/test/repo-onboarding.test.ts
@@ -0,0 +1,125 @@
+/**
+ *  MIT No Attribution
+ *
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Permission is hereby granted, free of charge, to any person obtaining a copy of
+ *  the Software without restriction, including without limitation the rights to
+ *  use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ *  the Software, and to permit persons to whom the Software is furnished to do so.
+ *
+ *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ *  SOFTWARE.
+ */
+
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
+import { checkRepoOnboarding, notOnboardedGuidance } from '../src/repo-onboarding';
+
+// CloudFormation — `getStackOutput` resolves RepoTableName from here.
+const cfnSend = jest.fn();
+jest.mock('@aws-sdk/client-cloudformation', () => {
+  const actual = jest.requireActual('@aws-sdk/client-cloudformation');
+  return {
+    ...actual,
+    CloudFormationClient: jest.fn(() => ({ send: cfnSend })),
+  };
+});
+
+// DynamoDB DocumentClient — the RepoTable GetItem goes through here.
+const ddbSend = jest.fn();
+jest.mock('@aws-sdk/lib-dynamodb', () => {
+  const actual = jest.requireActual('@aws-sdk/lib-dynamodb');
+  return {
+    ...actual,
+    DynamoDBDocumentClient: { from: jest.fn(() => ({ send: ddbSend })) },
+  };
+});
+
+const REPO = 'owner/repo';
+const OPTS = { region: 'us-west-2', stackName: 'backgroundagent-dev', repo: REPO };
+
+function stackWithRepoTable(): void {
+  cfnSend.mockResolvedValue({
+    Stacks: [{ Outputs: [{ OutputKey: 'RepoTableName', OutputValue: 'RepoTable' }] }],
+  });
+}
+
+describe('checkRepoOnboarding', () => {
+  beforeEach(() => {
+    cfnSend.mockReset();
+    ddbSend.mockReset();
+  });
+
+  test('returns onboarded when an active RepoTable row exists', async () => {
+    stackWithRepoTable();
+    ddbSend.mockResolvedValue({ Item: { repo: REPO, status: 'active' } });
+    await expect(checkRepoOnboarding(OPTS)).resolves.toEqual({ kind: 'onboarded' });
+    // The GetItem hit the table named by the stack output, keyed by repo.
+    const getCall = ddbSend.mock.calls.find((c) => c[0] instanceof GetCommand);
+    expect(getCall?.[0].input).toMatchObject({ TableName: 'RepoTable', Key: { repo: REPO } });
+  });
+
+  test('returns not-onboarded/missing when no row exists', async () => {
+    stackWithRepoTable();
+    ddbSend.mockResolvedValue({});
+    await expect(checkRepoOnboarding(OPTS)).resolves.toEqual({ kind: 'not-onboarded', reason: 'missing' });
+  });
+
+  test('returns not-onboarded/inactive when the row is not active', async () => {
+    stackWithRepoTable();
+    ddbSend.mockResolvedValue({ Item: { repo: REPO, status: 'removed' } });
+    await expect(checkRepoOnboarding(OPTS)).resolves.toEqual({ kind: 'not-onboarded', reason: 'inactive', status: 'removed' });
+  });
+
+  test('returns unverifiable when the stack has no RepoTableName output', async () => {
+    cfnSend.mockResolvedValue({ Stacks: [{ Outputs: [] }] });
+    const result = await checkRepoOnboarding(OPTS);
+    expect(result.kind).toBe('unverifiable');
+    expect(ddbSend).not.toHaveBeenCalled();
+  });
+
+  test('returns unverifiable when the stack does not exist', async () => {
+    const err = Object.assign(new Error('Stack with id backgroundagent-dev does not exist'), { name: 'ValidationError' });
+    cfnSend.mockRejectedValue(err);
+    const result = await checkRepoOnboarding(OPTS);
+    expect(result.kind).toBe('unverifiable');
+  });
+
+  test('returns unverifiable (not throw) when reading stack outputs errors', async () => {
+    // A non-"does not exist" failure (throttling, IAM) is rethrown by the
+    // internal getStackOutput and caught here as inconclusive.
+    cfnSend.mockRejectedValue(Object.assign(new Error('Throttling'), { name: 'Throttling' }));
+    const result = await checkRepoOnboarding(OPTS);
+    expect(result.kind).toBe('unverifiable');
+    if (result.kind === 'unverifiable') expect(result.detail).toContain('stack outputs');
+    expect(ddbSend).not.toHaveBeenCalled();
+  });
+
+  test('returns unverifiable (not throw) on a RepoTable read error (e.g. IAM gap)', async () => {
+    stackWithRepoTable();
+    ddbSend.mockRejectedValue(Object.assign(new Error('AccessDeniedException'), { name: 'AccessDeniedException' }));
+    const result = await checkRepoOnboarding(OPTS);
+    expect(result.kind).toBe('unverifiable');
+    if (result.kind === 'unverifiable') expect(result.detail).toContain('RepoTable');
+  });
+});
+
+describe('notOnboardedGuidance', () => {
+  test('mentions the repo, the 422 code, and the --skip escape hatch for a missing row', () => {
+    const lines = notOnboardedGuidance(REPO, { kind: 'not-onboarded', reason: 'missing' }).join('\n');
+    expect(lines).toContain(REPO);
+    expect(lines).toContain('REPO_NOT_ONBOARDED');
+    expect(lines).toContain('--skip-onboarding-check');
+    expect(lines).toContain('mise //cdk:deploy');
+  });
+
+  test('surfaces the offending status for an inactive row', () => {
+    const lines = notOnboardedGuidance(REPO, { kind: 'not-onboarded', reason: 'inactive', status: 'removed' }).join('\n');
+    expect(lines).toContain("status is 'removed'");
+  });
+});
diff --git a/docs/guides/JIRA_SETUP_GUIDE.md b/docs/guides/JIRA_SETUP_GUIDE.md
index 9503cf2d..04dc9f2b 100644
--- a/docs/guides/JIRA_SETUP_GUIDE.md
+++ b/docs/guides/JIRA_SETUP_GUIDE.md
@@ -8,9 +8,12 @@ Set up the ABCA Jira Cloud integration so that adding a label to a Jira issue tr
 - A Cognito user account configured (see [User guide](./USER_GUIDE.md))
 - A Jira Cloud site where you have **admin** access (to create the OAuth app and the webhook)
 - The `bgagent` CLI installed and logged in (`bgagent configure` + `bgagent login`)
+- **The target GitHub repository onboarded with a deployed Blueprint** — see the prerequisite below.
 
 > **Jira Cloud only.** Jira Server / Data Center are out of scope. The integration uses Jira REST v3 and Atlassian Cloud webhooks.
 
+> **The repo you map must already be onboarded.** A Jira project can only route tasks to a GitHub repository that has an **active Blueprint** — a `status='active'` row in the `RepoTable`, written when you instantiate a `Blueprint` construct in `cdk/src/stacks/agent.ts` and deploy. If you map a project to a repo with no Blueprint, the mapping is accepted but **every label trigger fails** at task creation with `422 REPO_NOT_ONBOARDED`, and no task is created. `bgagent jira map` checks this at map time and refuses (with guidance) unless you pass `--skip-onboarding-check`. Onboard the repo first — set `BLUEPRINT_REPO` / the `blueprintRepo` CDK context, or add a `new Blueprint(this, …, { repo: 'owner/repo', repoTable: repoTable.table })` in the stack, then `MISE_EXPERIMENTAL=1 mise //cdk:deploy`. See [Quick start → onboarding a repository](./QUICK_START.md) for the full steps.
+
 ## How it works
 
 A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
@@ -108,9 +111,12 @@ bgagent jira map <cloud-id> <PROJECT-KEY> --repo owner/repo
 - `<PROJECT-KEY>` — the Jira project key, e.g. `ENG` (uppercase, starts with a letter)
 - `--repo owner/repo` — the GitHub repository tasks from this project route to
 - `--label <name>` — trigger label (default `bgagent`)
+- `--skip-onboarding-check` — persist the mapping even if the repo has no active Blueprint (the mapping cannot trigger until one is deployed)
 
 This writes an `active` row keyed `<cloudId>#<projectKey>` into the project-mapping table. Requires admin IAM (it writes DynamoDB directly).
 
+Before writing, `map` verifies the `--repo` is onboarded (has an `active` row in the `RepoTable`). If it is not, the command **fails with remediation steps** instead of silently persisting a mapping that can never trigger (`422 REPO_NOT_ONBOARDED`). If the check cannot run (e.g. the stack predates the `RepoTableName` output, or your IAM principal cannot read the table), it warns and proceeds. Use `--skip-onboarding-check` to bypass the check intentionally — e.g. when you are deploying the Blueprint in the same change.
+
 ### 5. Link your Jira identity
 
 So tasks triggered from Jira attribute to your platform user (concurrency caps, billing, `bgagent list`), link your Atlassian `accountId` to your ABCA account. An admin issues you a one-time invite code, then you redeem it:
diff --git a/docs/guides/LINEAR_SETUP_GUIDE.md b/docs/guides/LINEAR_SETUP_GUIDE.md
index 423bd63a..04a76046 100644
--- a/docs/guides/LINEAR_SETUP_GUIDE.md
+++ b/docs/guides/LINEAR_SETUP_GUIDE.md
@@ -8,6 +8,9 @@ Set up the ABCA Linear integration so that applying a label to a Linear issue tr
 - A Cognito user account configured (see [User guide](./USER_GUIDE.md))
 - A Linear workspace where you have **admin** access
 - The `bgagent` CLI installed and logged in (`bgagent configure` + `bgagent login`)
+- **The target GitHub repository onboarded with a deployed Blueprint** — see the prerequisite below.
+
+> **The repo you map must already be onboarded.** A Linear project can only route tasks to a GitHub repository that has an **active Blueprint** — a `status='active'` row in the `RepoTable`, written when you instantiate a `Blueprint` construct in `cdk/src/stacks/agent.ts` and deploy. Linear shares the same task-creation onboarding gate as Jira: if you onboard a project to a repo with no Blueprint, the mapping is accepted but **every label trigger fails** with `422 REPO_NOT_ONBOARDED` and no task is created. `bgagent linear onboard-project` checks this at map time and refuses (with guidance) unless you pass `--skip-onboarding-check`. Onboard the repo first — set `BLUEPRINT_REPO` / the `blueprintRepo` CDK context, or add a `new Blueprint(this, …, { repo: 'owner/repo', repoTable: repoTable.table })` in the stack, then `MISE_EXPERIMENTAL=1 mise //cdk:deploy`. See [Quick start → onboarding a repository](./QUICK_START.md) for the full steps.
 
 ## How it works
 
@@ -88,7 +91,9 @@ bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca
 
 Default trigger label is `bgagent`; pass `--label <name>` to override.
 
-Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
+Before writing, `onboard-project` verifies the `--repo` is onboarded (has an `active` row in the `RepoTable`). If it is not, the command **fails with remediation steps** instead of silently persisting a mapping that can never trigger (`422 REPO_NOT_ONBOARDED`). If the check cannot run (e.g. the stack predates the `RepoTableName` output, or your IAM principal cannot read the table), it warns and proceeds.
+
+Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`, `--skip-onboarding-check` (persist the mapping even if the repo has no active Blueprint).
 
 ### 7. Test
 
diff --git a/docs/src/content/docs/using/Jira-setup-guide.md b/docs/src/content/docs/using/Jira-setup-guide.md
index c87540d2..f0f09d2c 100644
--- a/docs/src/content/docs/using/Jira-setup-guide.md
+++ b/docs/src/content/docs/using/Jira-setup-guide.md
@@ -12,9 +12,12 @@ Set up the ABCA Jira Cloud integration so that adding a label to a Jira issue tr
 - A Cognito user account configured (see [User guide](/using/overview))
 - A Jira Cloud site where you have **admin** access (to create the OAuth app and the webhook)
 - The `bgagent` CLI installed and logged in (`bgagent configure` + `bgagent login`)
+- **The target GitHub repository onboarded with a deployed Blueprint** — see the prerequisite below.
 
 > **Jira Cloud only.** Jira Server / Data Center are out of scope. The integration uses Jira REST v3 and Atlassian Cloud webhooks.
 
+> **The repo you map must already be onboarded.** A Jira project can only route tasks to a GitHub repository that has an **active Blueprint** — a `status='active'` row in the `RepoTable`, written when you instantiate a `Blueprint` construct in `cdk/src/stacks/agent.ts` and deploy. If you map a project to a repo with no Blueprint, the mapping is accepted but **every label trigger fails** at task creation with `422 REPO_NOT_ONBOARDED`, and no task is created. `bgagent jira map` checks this at map time and refuses (with guidance) unless you pass `--skip-onboarding-check`. Onboard the repo first — set `BLUEPRINT_REPO` / the `blueprintRepo` CDK context, or add a `new Blueprint(this, …, { repo: 'owner/repo', repoTable: repoTable.table })` in the stack, then `MISE_EXPERIMENTAL=1 mise //cdk:deploy`. See [Quick start → onboarding a repository](/getting-started/quick-start) for the full steps.
+
 ## How it works
 
 A Jira-site admin creates an Atlassian OAuth 2.0 (3LO) app and authorizes it on the site. The OAuth token bundle is stored in a per-tenant Secrets Manager secret (`bgagent-jira-oauth-<cloudId>`). When a user adds the trigger label to a Jira issue, Jira fires a webhook to ABCA; the receiver verifies the `X-Hub-Signature` HMAC, dedupes, and async-invokes the processor, which resolves the tenant, looks up the project→repo mapping, and creates a task. The agent clones the repo, opens a PR, and comments on the Jira issue via the Jira REST v3 API (using the same stored OAuth token).
@@ -112,9 +115,12 @@ bgagent jira map <cloud-id> <PROJECT-KEY> --repo owner/repo
 - `<PROJECT-KEY>` — the Jira project key, e.g. `ENG` (uppercase, starts with a letter)
 - `--repo owner/repo` — the GitHub repository tasks from this project route to
 - `--label <name>` — trigger label (default `bgagent`)
+- `--skip-onboarding-check` — persist the mapping even if the repo has no active Blueprint (the mapping cannot trigger until one is deployed)
 
 This writes an `active` row keyed `<cloudId>#<projectKey>` into the project-mapping table. Requires admin IAM (it writes DynamoDB directly).
 
+Before writing, `map` verifies the `--repo` is onboarded (has an `active` row in the `RepoTable`). If it is not, the command **fails with remediation steps** instead of silently persisting a mapping that can never trigger (`422 REPO_NOT_ONBOARDED`). If the check cannot run (e.g. the stack predates the `RepoTableName` output, or your IAM principal cannot read the table), it warns and proceeds. Use `--skip-onboarding-check` to bypass the check intentionally — e.g. when you are deploying the Blueprint in the same change.
+
 ### 5. Link your Jira identity
 
 So tasks triggered from Jira attribute to your platform user (concurrency caps, billing, `bgagent list`), link your Atlassian `accountId` to your ABCA account. An admin issues you a one-time invite code, then you redeem it:
diff --git a/docs/src/content/docs/using/Linear-setup-guide.md b/docs/src/content/docs/using/Linear-setup-guide.md
index aa39d07c..4e55ab1e 100644
--- a/docs/src/content/docs/using/Linear-setup-guide.md
+++ b/docs/src/content/docs/using/Linear-setup-guide.md
@@ -12,6 +12,9 @@ Set up the ABCA Linear integration so that applying a label to a Linear issue tr
 - A Cognito user account configured (see [User guide](/using/overview))
 - A Linear workspace where you have **admin** access
 - The `bgagent` CLI installed and logged in (`bgagent configure` + `bgagent login`)
+- **The target GitHub repository onboarded with a deployed Blueprint** — see the prerequisite below.
+
+> **The repo you map must already be onboarded.** A Linear project can only route tasks to a GitHub repository that has an **active Blueprint** — a `status='active'` row in the `RepoTable`, written when you instantiate a `Blueprint` construct in `cdk/src/stacks/agent.ts` and deploy. Linear shares the same task-creation onboarding gate as Jira: if you onboard a project to a repo with no Blueprint, the mapping is accepted but **every label trigger fails** with `422 REPO_NOT_ONBOARDED` and no task is created. `bgagent linear onboard-project` checks this at map time and refuses (with guidance) unless you pass `--skip-onboarding-check`. Onboard the repo first — set `BLUEPRINT_REPO` / the `blueprintRepo` CDK context, or add a `new Blueprint(this, …, { repo: 'owner/repo', repoTable: repoTable.table })` in the stack, then `MISE_EXPERIMENTAL=1 mise //cdk:deploy`. See [Quick start → onboarding a repository](/getting-started/quick-start) for the full steps.
 
 ## How it works
 
@@ -92,7 +95,9 @@ bgagent linear onboard-project <project-uuid> --repo owner/repo --label abca
 
 Default trigger label is `bgagent`; pass `--label <name>` to override.
 
-Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`.
+Before writing, `onboard-project` verifies the `--repo` is onboarded (has an `active` row in the `RepoTable`). If it is not, the command **fails with remediation steps** instead of silently persisting a mapping that can never trigger (`422 REPO_NOT_ONBOARDED`). If the check cannot run (e.g. the stack predates the `RepoTableName` output, or your IAM principal cannot read the table), it warns and proceeds.
+
+Optional flags on `onboard-project`: `--team-id` (Linear team UUID, debug only), `--region`, `--stack-name`, `--skip-onboarding-check` (persist the mapping even if the repo has no active Blueprint).
 
 ### 7. Test