feat(config): add integrationBranch setting and PR base branch guard

.agentkit/engines/node/src/synchronize.mjs

@@ -2006,6 +2006,8 @@ export async function runSync({ agentkitRoot, projectRoot, flags }) {
       overlaySettings.repoName ||
       repoName,
     defaultBranch: overlaySettings.defaultBranch || 'main',
+    integrationBranch:
+      overlaySettings.integrationBranch || overlaySettings.defaultBranch || 'main',
     primaryStack: overlaySettings.primaryStack || 'auto',
     commandPrefix: overlaySettings.commandPrefix || null,
     syncDate: new Date().toISOString().slice(0, 10),

.agentkit/overlays/__TEMPLATE__/settings.yaml

@@ -1,7 +1,8 @@
 # Repo-specific overlay settings
 # This file is copied by `agentkit init` and customized per repo.
 repoName: __TEMPLATE__
-defaultBranch: main
+defaultBranch: main          # Repository default branch (usually main or master)
+integrationBranch: main      # Branch PRs should target (often dev or main; defaults to defaultBranch)
 primaryStack: auto
 windowsFirst: true
 

.agentkit/overlays/retort/settings.yaml

@@ -0,0 +1,24 @@
+# Retort repo overlay settings
+# This is retort's own overlay — configures how the framework generates output for itself.
+repoName: retort
+defaultBranch: main          # Production branch — never commit directly
+integrationBranch: dev       # PRs must target dev, not main
+primaryStack: auto
+windowsFirst: true
+
+aiSynthesisLayer: false
+
+renderTargets:
+  - claude
+  - cursor
+  - windsurf
+  - copilot
+  - gemini
+  - codex
+  - warp
+  - cline
+  - roo
+  - ai
+  - mcp
+
+featurePreset: standard

.agentkit/templates/claude/CLAUDE.md

@@ -12,6 +12,7 @@ This repository uses **Retort** to manage AI agent team workflows across multipl
 
 - **Repository**: {{repoName}}
 - **Default Branch**: {{defaultBranch}}
+- **Integration Branch** (PR target): {{integrationBranch}}
 - **Framework Version**: {{version}}
   {{#if projectPhase}}
 
@@ -356,6 +357,16 @@ Then commit the regenerated output. The CI drift check **will fail** if generate
 
 Feature branches: `type/short-description` (e.g., `feat/add-user-auth`, `fix/token-refresh`)
 
+### PR Target Branch
+
+All PRs **must** target `{{integrationBranch}}` — not `{{defaultBranch}}` or any other branch unless explicitly instructed:
+
+```bash
+gh pr create --base {{integrationBranch}} --title "type(scope): description"
+```
+
+The integration branch (`{{integrationBranch}}`) is the configured PR target for this repo. Creating PRs against `{{defaultBranch}}` directly causes reverse-merge noise and bypasses the integration pipeline. A hookify rule in `.claude/rules/pr-base-branch.md` enforces this at runtime.
+
 ## Safety Rules
 
 1. **Never** commit secrets, API keys, or credentials

.agentkit/templates/claude/hooks/protect-templates.ps1

@@ -52,7 +52,7 @@ $protectedPatterns = @(
 
 foreach ($pattern in $protectedPatterns) {
     if ($filePath -match $pattern) {
-        $reason = "Blocked: '$filePath' is an Retort source file. These files are the upstream source-of-truth and must not be modified directly by AI agents. To propose changes, create a PR to the agentkit-forge repository targeting the relevant spec or template. If you need to change project configuration, edit the YAML specs in .agentkit/spec/ and run 'pnpm -C .agentkit retort:sync'."
+        $reason = "Blocked: '$filePath' is a Retort source file. These files are the upstream source-of-truth and must not be modified directly by AI agents. To propose changes, create a PR to the agentkit-forge repository targeting the relevant spec or template. If you need to change project configuration, edit the YAML specs in .agentkit/spec/ and run 'pnpm -C .agentkit retort:sync'."
         @{
             hookSpecificOutput = @{
                 hookEventName           = 'PreToolUse'

.agentkit/templates/claude/hooks/protect-templates.sh

@@ -47,7 +47,7 @@ PROTECTED_PATTERNS=(
 for pattern in "${PROTECTED_PATTERNS[@]}"; do
     if echo "$FILE_PATH" | grep -qE "$pattern"; then
         jq -n \
-            --arg reason "Blocked: '${FILE_PATH}' is an Retort source file. These files are the upstream source-of-truth and must not be modified directly by AI agents. To propose changes, create a PR to the agentkit-forge repository targeting the relevant spec or template. If you need to change project configuration, edit the YAML specs in .agentkit/spec/ and run '{{packageManager}} -C .agentkit retort:sync'." \
+            --arg reason "Blocked: '${FILE_PATH}' is a Retort source file. These files are the upstream source-of-truth and must not be modified directly by AI agents. To propose changes, create a PR to the agentkit-forge repository targeting the relevant spec or template. If you need to change project configuration, edit the YAML specs in .agentkit/spec/ and run '{{packageManager}} -C .agentkit retort:sync'." \
             '{
                 hookSpecificOutput: {
                     hookEventName: "PreToolUse",

.agentkit/templates/claude/rules/pr-base-branch.md

@@ -0,0 +1,50 @@
+<!-- GENERATED by Retort v{{version}} — DO NOT EDIT -->
+<!-- Source: .agentkit/overlays/{{repoName}}/settings.yaml (integrationBranch) -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
+<!-- generated_by: {{lastAgent}} | last_model: {{lastModel}} | last_updated: {{syncDate}} -->
+<!-- Format: Hookify guard rule. -->
+
+# PR Base Branch Guard
+
+Always use `--base {{integrationBranch}}` when creating pull requests in **{{repoName}}**.
+
+## Rule
+
+**Event**: bash
+**Action**: warn
+**Pattern**: `gh pr create` without `--base {{integrationBranch}}`
+
+## Why This Matters
+
+This repository uses a two-branch model:
+
+- `{{defaultBranch}}` — production branch, never targeted directly by feature PRs
+- `{{integrationBranch}}` — integration branch, the correct PR target for all feature work
+
+Creating PRs against `{{defaultBranch}}` instead of `{{integrationBranch}}` triggers an automatic reverse-merge PR (merging `{{defaultBranch}}` back into `{{integrationBranch}}`), which creates noise and bypasses the integration pipeline.
+
+## Correct Usage
+
+```bash
+# Always specify --base explicitly
+gh pr create --base {{integrationBranch}} --title "type(scope): description"
+```
+
+## Incorrect Usage
+
+```bash
+# These will target the wrong branch
+gh pr create --title "type(scope): description"
+gh pr create --base {{defaultBranch}} --title "type(scope): description"
+```
+
+## Configuration
+
+The integration branch is configured in `.agentkit/overlays/{{repoName}}/settings.yaml`:
+
+```yaml
+defaultBranch: {{defaultBranch}}
+integrationBranch: {{integrationBranch}}
+```
+
+To change the integration branch, update `settings.yaml` and run `pnpm -C .agentkit retort:sync`.

.agents/skills/analyze-agents/SKILL.md

@@ -3,14 +3,14 @@ name: 'analyze-agents'
 description: 'Generates a comprehensive agent/team relationship matrix. Analyzes dependencies, notifications, handoffs, coverage gaps, bottlenecks, and consolidation opportunities across all teams and agents.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # analyze-agents
 
@@ -36,7 +36,7 @@ Invoke this skill when you need to perform the `analyze-agents` operation.
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/backlog/SKILL.md

@@ -3,14 +3,14 @@ name: 'backlog'
 description: 'Displays a consolidated backlog view from all sources (external tracker, discovery, healthcheck, code TODOs, review findings, manual entries). Supports filtering and multiple output formats for CLI and future UI consumption.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # backlog
 
@@ -36,7 +36,7 @@ Invoke this skill when you need to perform the `backlog` operation.
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/brand/SKILL.md

@@ -3,14 +3,14 @@ name: 'brand'
 description: 'Manage the project brand spec (brand.yaml) and editor theme. Supports validation, palette preview, theme mapping, contrast auditing, scaffolding, and regeneration of editor theme files.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # brand
 
@@ -36,7 +36,7 @@ Invoke this skill when you need to perform the `brand` operation.
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/build/SKILL.md

@@ -3,14 +3,14 @@ name: 'build'
 description: 'Builds the project using the detected tech stack's build command. Supports targeting specific packages in a monorepo or building the entire workspace.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # build
 
@@ -59,7 +59,7 @@ Report: detected stack, scope, exact command, status (PASS/FAIL), duration, arti
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/check/SKILL.md

@@ -3,14 +3,14 @@ name: 'check'
 description: 'Runs all quality checks for the repository: type checking, linting, formatting validation, and test suites. Returns a unified pass/fail status with detailed breakdowns per check category.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # check
 
@@ -51,7 +51,7 @@ Produce: Quality Gate Results table (Step | Status | Duration | Details), Overal
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/cost-centres/SKILL.md

@@ -3,14 +3,14 @@ name: 'cost-centres'
 description: 'Cost centre management for cloud infrastructure. Manages budget allocations, resource group mappings, tag compliance, and spend tracking. Requires a FinOps-enabled overlay (finops rule domain). For AI session cost tracking, use /cost instead.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # cost-centres
 
@@ -36,7 +36,7 @@ Invoke this skill when you need to perform the `cost-centres` operation.
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/cost/SKILL.md

@@ -3,14 +3,14 @@ name: 'cost'
 description: 'Session cost and usage tracking. Shows session summaries, lists recent sessions, and generates aggregate usage reports. Tracks session duration, commands run, and files modified via lifecycle hooks.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # cost
 
@@ -44,7 +44,7 @@ Invoke this skill when you need to perform the `cost` operation.
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/deploy/SKILL.md

@@ -3,14 +3,14 @@ name: 'deploy'
 description: 'Triggers a deployment pipeline or generates deployment artifacts. Validates pre-deployment checks (build, test, lint) before proceeding. Supports dry-run mode for safety.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # deploy
 
@@ -65,7 +65,7 @@ Report: service, environment, platform, status, timeline, command output, post-d
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown
 

.agents/skills/discover/SKILL.md

@@ -3,14 +3,14 @@ name: 'discover'
 description: 'Scans the repository to build a comprehensive understanding of the project structure, tech stacks in use, team boundaries, and architectural patterns. Outputs a structured discovery report used by other commands.'
 generated_by: 'agentkit-forge'
 last_model: 'sync-engine'
-last_updated: '2026-03-17'
+last_updated: '2026-03-21'
 # Format: YAML frontmatter + Markdown body. Codex agent skill definition.
 # Docs: https://developers.openai.com/codex/guides/agents-md
 ---
 
-<!-- GENERATED by AgentKit Forge v3.1.0 — DO NOT EDIT -->
-<!-- Source: .agentkit/spec + .agentkit/overlays/agentkit-forge -->
-<!-- Regenerate: pnpm -C .agentkit agentkit:sync -->
+<!-- GENERATED by Retort v3.1.0 — DO NOT EDIT -->
+<!-- Source: .agentkit/spec + .agentkit/overlays/retort -->
+<!-- Regenerate: pnpm -C .agentkit retort:sync -->
 
 # discover
 
@@ -47,7 +47,7 @@ Create or update `AGENT_TEAMS.md` with: Repository Profile (primary stack, build
 
 ## Project Context
 
-- Repository: agentkit-forge
+- Repository: retort
 - Default branch: main
   - Tech stack: javascript, yaml, markdown