@empire-builder-kit/nx 1.0.0-beta.5 → 1.0.0-beta.7

package/src/generators/preset/workspace-files.js

@@ -5,6 +5,8 @@ exports.renderWorkspaceFiles = renderWorkspaceFiles;
 exports.renderWorkspaceRootFilePlan = renderWorkspaceRootFilePlan;
 exports.renderFoundationFilePlan = renderFoundationFilePlan;
 const index_js_1 = require("../../ownership/index.js");
+const index_js_2 = require("../../git-policy/index.js");
+const index_js_3 = require("../../repository-policy/index.js");
 const TOOL_VERSIONS = {
     eslint: '^9.8.0',
     eslintJs: '^9.8.0',
@@ -25,8 +27,15 @@ const FOUNDATION_OWNERSHIP_PATH = `${FOUNDATION_ROOT}.ebk/ownership.json`;
 const FOUNDATION_TOOL_OWNED_PATHS = new Set(['sst-env.d.ts']);
 const WORKSPACE_OWNERSHIP_PATH = '.ebk/ownership.json';
 const WORKSPACE_SEEDED_PATHS = new Set([
+    '.github/CODEOWNERS',
+    'AGENTS.md',
+    'CLAUDE.md',
     'README.md',
     'docs/architecture.md',
+    'docs/git-workflow.md',
+    'docs/repository-operating-policy.md',
+    'docs/work-markers.md',
+    'ebk.repository-policy.json',
     'package.json',
 ]);
 exports.WORKSPACE_PROJECT_MANAGED_JSON_POINTERS = [
@@ -34,10 +43,14 @@ exports.WORKSPACE_PROJECT_MANAGED_JSON_POINTERS = [
     '/$schema',
     '/projectType',
     '/tags',
+    '/targets/deployment-plan',
     '/targets/dev',
     '/targets/dev-doctor',
     '/targets/dev-setup',
+    '/targets/github-bootstrap',
+    '/targets/install-git-hooks',
     '/targets/verify',
+    '/targets/work-markers',
     '/targets/workspace-health',
 ];
 const FOUNDATION_SEEDED_PATHS = new Set([
@@ -101,13 +114,24 @@ function createWorkspaceOwnership(files, frameworkVersion) {
 }
 function renderWorkspaceFiles(options) {
     const { frameworkVersion, name } = options;
+    const checkoutAction = (0, index_js_2.pinnedAction)(index_js_2.GITHUB_ACTION_PINS.checkout);
+    const configureAwsAction = (0, index_js_2.pinnedAction)(index_js_2.GITHUB_ACTION_PINS.configureAwsCredentials);
+    const pnpmAction = (0, index_js_2.pinnedAction)(index_js_2.GITHUB_ACTION_PINS.pnpmSetup);
+    const setupNodeAction = (0, index_js_2.pinnedAction)(index_js_2.GITHUB_ACTION_PINS.setupNode);
     const files = {
+        '.github/CODEOWNERS': `# Replace this placeholder with the GitHub user or team that owns protected source.
+# GitHub bootstrap remains blocked until a non-placeholder catch-all owner is committed.
+* @REPLACE_WITH_GITHUB_CODE_OWNER
+`,
+        '.github/actions-pins.json': json(index_js_2.GITHUB_ACTION_PINS),
         '.github/workflows/ci.yml': `name: Verify
 
 on:
   pull_request:
+    branches: [develop, main]
   push:
-    branches: [main]
+    branches: [develop, main]
+  workflow_dispatch:
 
 concurrency:
   group: verify-\${{ github.ref }}
@@ -117,12 +141,29 @@ permissions:
   contents: read
 
 jobs:
+  policy:
+    name: policy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ${checkoutAction}
+        with:
+          fetch-depth: 0
+          ref: \${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: node tools/ebk-git-policy.mjs
+
   verify:
+    name: verify
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: pnpm/action-setup@v5
-      - uses: actions/setup-node@v6
+      - uses: ${checkoutAction}
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
         with:
           node-version: 22
           cache: pnpm
@@ -133,49 +174,289 @@ jobs:
         '.github/workflows/deploy.yml': `name: Deploy
 
 on:
+  push:
+    branches: [develop, main]
   workflow_dispatch:
     inputs:
-      stage:
-        description: Deployment stage
-        required: true
-        default: development
-        type: choice
-        options: [development, staging, production]
       action:
         description: Lifecycle action
         required: true
         default: deploy
         type: choice
         options: [deploy, refresh, unlock, remove]
+      project:
+        description: Required registered project for explicit unlock or remove
+        required: false
+        type: string
 
 concurrency:
-  group: deploy-\${{ inputs.stage }}
+  group: deploy-\${{ github.ref }}
   cancel-in-progress: false
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
-  deploy:
+  route:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate protected ref
+        env:
+          EBK_PROTECTED_REF: \${{ github.ref }}
+        run: |
+          case "$EBK_PROTECTED_REF" in
+            refs/heads/develop|refs/heads/main) ;;
+            *) echo 'Protected lifecycle must be dispatched from develop or main'; exit 1 ;;
+          esac
+
+  plan-staging:
+    needs: route
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    outputs:
+      foundation_project: \${{ steps.plan.outputs.foundation_project }}
+      has_slices: \${{ steps.plan.outputs.has_slices }}
+      ordered_projects: \${{ steps.plan.outputs.ordered_projects }}
+      slice_projects: \${{ steps.plan.outputs.slice_projects }}
+    steps:
+      - uses: ${checkoutAction}
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - id: plan
+        env:
+          EBK_ACTION: \${{ github.event_name == 'push' && 'deploy' || inputs.action }}
+          EBK_PROJECT: \${{ inputs.project || '' }}
+        run: |
+          args=("--action=$EBK_ACTION" "--stage=staging")
+          if [ -n "$EBK_PROJECT" ]; then args+=("--project=$EBK_PROJECT"); fi
+          pnpm nx run ${name}:deployment-plan -- "\${args[@]}"
+
+  plan-production:
+    needs: route
     if: github.ref == 'refs/heads/main'
-    environment: \${{ inputs.stage }}
+    runs-on: ubuntu-latest
+    outputs:
+      foundation_project: \${{ steps.plan.outputs.foundation_project }}
+      foundation_profile: \${{ steps.plan.outputs.foundation_profile }}
+      has_slices: \${{ steps.plan.outputs.has_slices }}
+      ordered_projects: \${{ steps.plan.outputs.ordered_projects }}
+      slice_projects: \${{ steps.plan.outputs.slice_projects }}
+    steps:
+      - uses: ${checkoutAction}
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - id: plan
+        env:
+          EBK_ACTION: \${{ github.event_name == 'push' && 'deploy' || inputs.action }}
+          EBK_PROJECT: \${{ inputs.project || '' }}
+        run: |
+          args=("--action=$EBK_ACTION" "--stage=production")
+          if [ -n "$EBK_PROJECT" ]; then args+=("--project=$EBK_PROJECT"); fi
+          pnpm nx run ${name}:deployment-plan -- "\${args[@]}"
+
+  deploy-staging:
+    name: deploy staging
+    needs: plan-staging
+    environment: staging
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      AWS_DEPLOY_ROLE_ARN: \${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+      AWS_EXPECTED_ACCOUNT_ID: \${{ vars.AWS_EXPECTED_ACCOUNT_ID }}
+      AWS_REGION: \${{ vars.AWS_REGION }}
+      EBK_ACTION: \${{ github.event_name == 'push' && 'deploy' || inputs.action }}
+      EBK_STAGE: staging
+      FOUNDATION_PROJECT: \${{ needs.plan-staging.outputs.foundation_project }}
+      ORDERED_PROJECTS: \${{ needs.plan-staging.outputs.ordered_projects }}
+      SLICE_PROJECTS: \${{ needs.plan-staging.outputs.slice_projects }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ${checkoutAction}
+      - name: Validate environment configuration
+        run: |
+          test -n "$AWS_DEPLOY_ROLE_ARN" || { echo 'staging AWS_DEPLOY_ROLE_ARN is required'; exit 1; }
+          test -n "$AWS_EXPECTED_ACCOUNT_ID" || { echo 'staging AWS_EXPECTED_ACCOUNT_ID is required'; exit 1; }
+          test -n "$AWS_REGION" || { echo 'staging AWS_REGION is required'; exit 1; }
+          case "$AWS_DEPLOY_ROLE_ARN" in
+            arn:aws:iam::$AWS_EXPECTED_ACCOUNT_ID:role/*) ;;
+            *) echo 'Deployment role does not belong to the expected staging account'; exit 1 ;;
+          esac
+      - uses: ${configureAwsAction}
+        with:
+          role-to-assume: \${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+          role-session-name: ebk-\${{ github.run_id }}-\${{ github.run_attempt }}
+          aws-region: \${{ vars.AWS_REGION }}
+      - name: Verify assumed account
+        run: test "$(aws sts get-caller-identity --query Account --output text)" = "$AWS_EXPECTED_ACCOUNT_ID"
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Run ordered lifecycle
+        run: |
+          if [ -n "$FOUNDATION_PROJECT" ]; then
+            pnpm nx run "$FOUNDATION_PROJECT:$EBK_ACTION" --stage="$EBK_STAGE"
+          fi
+          if [ -n "$SLICE_PROJECTS" ]; then
+            pnpm nx run-many -t "$EBK_ACTION" --projects="$SLICE_PROJECTS" --stage="$EBK_STAGE" --parallel=1
+          fi
+
+  deploy-production:
+    name: deploy production
+    needs: plan-production
+    environment: production
+    permissions:
+      contents: read
+      id-token: write
     env:
+      AWS_DEPLOY_ROLE_ARN: \${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+      AWS_EXPECTED_ACCOUNT_ID: \${{ vars.AWS_EXPECTED_ACCOUNT_ID }}
+      AWS_REGION: \${{ vars.AWS_REGION }}
+      EBK_ACTION: \${{ github.event_name == 'push' && 'deploy' || inputs.action }}
       EBK_ALLOW_PRODUCTION_REMOVE: \${{ vars.EBK_ALLOW_PRODUCTION_REMOVE || 'false' }}
+      EBK_STAGE: production
+      FOUNDATION_PROJECT: \${{ needs.plan-production.outputs.foundation_project }}
+      ORDERED_PROJECTS: \${{ needs.plan-production.outputs.ordered_projects }}
+      SLICE_PROJECTS: \${{ needs.plan-production.outputs.slice_projects }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: aws-actions/configure-aws-credentials@v6
+      - uses: ${checkoutAction}
+      - name: Validate environment configuration
+        run: |
+          test -n "$AWS_DEPLOY_ROLE_ARN" || { echo 'production AWS_DEPLOY_ROLE_ARN is required'; exit 1; }
+          test -n "$AWS_EXPECTED_ACCOUNT_ID" || { echo 'production AWS_EXPECTED_ACCOUNT_ID is required'; exit 1; }
+          test -n "$AWS_REGION" || { echo 'production AWS_REGION is required'; exit 1; }
+          case "$AWS_DEPLOY_ROLE_ARN" in
+            arn:aws:iam::$AWS_EXPECTED_ACCOUNT_ID:role/*) ;;
+            *) echo 'Deployment role does not belong to the expected production account'; exit 1 ;;
+          esac
+      - uses: ${configureAwsAction}
         with:
           role-to-assume: \${{ secrets.AWS_DEPLOY_ROLE_ARN }}
-          aws-region: \${{ vars.AWS_REGION || 'us-east-1' }}
-      - uses: pnpm/action-setup@v5
-      - uses: actions/setup-node@v6
+          role-session-name: ebk-\${{ github.run_id }}-\${{ github.run_attempt }}
+          aws-region: \${{ vars.AWS_REGION }}
+      - name: Verify assumed account
+        run: test "$(aws sts get-caller-identity --query Account --output text)" = "$AWS_EXPECTED_ACCOUNT_ID"
+      - uses: ${pnpmAction}
+      - uses: ${setupNodeAction}
         with:
           node-version: 22
           cache: pnpm
       - run: pnpm install --frozen-lockfile
-      - run: pnpm nx run-many -t \${{ inputs.action }} --stage=\${{ inputs.stage }} --parallel=1
+      - name: Run ordered lifecycle
+        run: |
+          if [ -n "$FOUNDATION_PROJECT" ]; then
+            pnpm nx run "$FOUNDATION_PROJECT:$EBK_ACTION" --stage="$EBK_STAGE"
+          fi
+          if [ -n "$SLICE_PROJECTS" ]; then
+            pnpm nx run-many -t "$EBK_ACTION" --projects="$SLICE_PROJECTS" --stage="$EBK_STAGE" --parallel=1
+          fi
+`,
+        '.github/workflows/sync-back.yml': `name: Sync production history
+
+on:
+  workflow_run:
+    workflows: [Deploy]
+    types: [completed]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  sync-back:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Open or locate main-to-develop pull request
+        env:
+          GH_TOKEN: \${{ github.token }}
+          GH_REPO: \${{ github.repository }}
+        run: |
+          number=$(gh pr list --state open --head main --base develop --json number --jq '.[0].number // empty')
+          if [ -z "$number" ]; then
+            gh pr create \
+              --head main \
+              --base develop \
+              --title 'chore: sync production history to develop' \
+              --body 'Managed EBK sync-back. Review and merge; this workflow never pushes or auto-merges.'
+            number=$(gh pr list --state open --head main --base develop --json number --jq '.[0].number')
+          fi
+          echo "Sync-back pull request #$number is ready for review."
+
+          head_sha=$(gh pr view "$number" --json headRefOid --jq '.headRefOid')
+          for attempt in 1 2 3 4 5 6; do
+            runs=$(gh api \
+              -H 'Accept: application/vnd.github+json' \
+              "/repos/$GH_REPO/actions/workflows/ci.yml/runs?event=pull_request&head_sha=$head_sha" \
+              --jq '.total_count')
+            if [ "$runs" -gt 0 ]; then
+              echo 'Pull-request verification run materialized; approve it if GitHub marks it approval-required.'
+              exit 0
+            fi
+            sleep 5
+          done
+          echo 'No pull-request verification run materialized. Close and reopen the sync pull request as a human, then approve its workflows.'
+          exit 1
+`,
+        'tools/ebk-pre-push.mjs': `import { createInterface } from 'node:readline';
+
+const protectedRefs = new Set(['refs/heads/develop', 'refs/heads/main']);
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let rejected = false;
+
+for await (const line of lines) {
+  const [, , remoteRef] = line.trim().split(/\\s+/);
+  if (!protectedRefs.has(remoteRef)) continue;
+  rejected = true;
+  const branch = remoteRef.slice('refs/heads/'.length);
+  const route = branch === 'main'
+    ? 'develop -> main promotion'
+    : 'feature -> develop or main -> develop sync-back';
+  console.error('Direct push to ' + branch + ' rejected. Use a reviewed ' + route + ' pull request.');
+}
+
+if (rejected) process.exitCode = 1;
+`,
+        'tools/install-ebk-hooks.mjs': `import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const marker = '# Empire Builder Kit managed pre-push hook';
+const resolved = spawnSync('git', ['rev-parse', '--git-path', 'hooks/pre-push'], {
+  encoding: 'utf8',
+  shell: false,
+});
+if (resolved.status !== 0 || !resolved.stdout.trim()) {
+  console.error(resolved.stderr.trim() || 'Unable to resolve the repository-local Git hook path.');
+  process.exit(1);
+}
+
+const hookPath = resolved.stdout.trim();
+if (existsSync(hookPath) && !readFileSync(hookPath, 'utf8').includes(marker)) {
+  console.error('A non-EBK pre-push hook already exists at ' + hookPath + '; preserve or compose it manually.');
+  process.exit(1);
+}
+
+writeFileSync(
+  hookPath,
+  '#!/bin/sh\\n' + marker + '\\nnode tools/ebk-pre-push.mjs\\n',
+  'utf8',
+);
+chmodSync(hookPath, 0o755);
+console.log('Installed the repository-local EBK pre-push hook at ' + hookPath + '.');
 `,
         '.gitignore': `.nx/cache
 .nx/workspace-data
@@ -200,6 +481,36 @@ dist
 pnpm-lock.yaml
 `,
         '.prettierrc.json': json({ singleQuote: true }),
+        'AGENTS.md': `# Coding agent instructions
+
+Use \`pnpm nx\` for workspace tasks and read the repository runbooks before changing
+infrastructure or protected deployment policy. Preserve the ownership boundary recorded in
+\`.ebk/ownership.json\`: managed files belong to EBK, seeded files are generated starting
+points that adopters may change, and unrecorded files are adopter-owned.
+
+## Work markers
+
+Run \`pnpm nx run ${name}:work-markers\` when beginning or handing off implementation work.
+Search results are durable pointers to custom or nondeterministic work that the deterministic
+generator cannot complete safely. Read the marker's self-contained description and its
+\`GH:<number>\` or \`PLAN:<phase>/<slug>\` reference before acting.
+
+Blueprint and repository upgrades may also add a marker to an editable surface when preserved
+custom code must be reconciled with the new contract. Treat that marker as incomplete upgrade
+work: adapt the custom code, run the relevant verification, retain evidence, and then remove it.
+
+Generators and agents may add markers only to seeded or adopter-owned source files. Never add
+one to a managed file or edit managed output to resolve one. Complete the referenced work,
+preserve relevant tests and evidence, then remove the marker. \`EBK-SECURITY\` and
+\`EBK-BLOCKER\` prevent staging and production deploy or refresh; remove and unlock recovery
+remain available. See \`docs/work-markers.md\` for the fixed vocabulary and syntax.
+`,
+        'CLAUDE.md': `# Claude workspace guidance
+
+Read and follow \`AGENTS.md\`, including its generated-file ownership rules and work-marker
+workflow. Before implementing or handing off work, run
+\`pnpm nx run ${name}:work-markers\` and inspect every reported reference.
+`,
         'eslint.config.mjs': `import eslint from '@eslint/js';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
@@ -223,6 +534,8 @@ This workspace was created with Empire Builder Kit v1.
 1. Review \`docs/architecture.md\`.
 2. Review the generated Foundation before deploying it.
 3. Add product slices through the Empire Builder Kit Nx plugin.
+4. Review \`docs/repository-operating-policy.md\` and \`docs/git-workflow.md\` before enabling production.
+5. Read \`AGENTS.md\` and \`docs/work-markers.md\` before assigning generated customization work to agents.
 
 For one-origin fleet development, first run \`pnpm nx run ${name}:dev-setup\`, inspect the
 generated root certificate, then explicitly approve \`--trust --portless\`. Diagnose without
@@ -246,9 +559,187 @@ Foundation implementation files.
 Canonical consumer stages use the matching \`development\`, \`staging\`, or \`production\`
 Foundation. Personal and preview consumer stages may use only the \`development\` Foundation.
 `,
+        'docs/git-workflow.md': `# Protected Git workflow
+
+Ordinary work starts from \`develop\` and returns through a reviewed pull request to
+\`develop\`. A production promotion is exactly \`develop\` to \`main\`. After production,
+review and merge the managed \`main\` to \`develop\` sync-back pull request before ordinary
+work resumes.
+
+Both protected branches require the stable \`policy\` and \`verify\` checks, one approving
+review including an approval from the committed catch-all CODEOWNER and someone other than the
+most recent pusher, dismissed stale reviews, resolved conversations, and merge commits. Replace
+the placeholder in \`.github/CODEOWNERS\` with a GitHub user or team that has repository access
+before bootstrap. An approval from \`github-actions[bot]\` cannot satisfy the independent
+code-owner gate; the Actions repository setting is needed to create the managed sync-back pull
+request, not to approve it.
+Direct updates, force pushes, deletion, squash merging, and rebase merging are prohibited.
+GitHub rulesets, environments, and AWS IAM are the authorization boundaries; local hooks are
+only defense in depth.
+
+The \`staging\` environment accepts only \`develop\`; \`production\` accepts only \`main\`.
+The committed \`productionApproval.mode\` selects one of two production authorization
+contracts:
+
+- \`promotion-pr\` is compatible with private repositories on GitHub Team. The required
+  non-author CODEOWNER approval on the exact \`develop\` to \`main\` promotion pull request
+  is the production authorization. Merging that pull request starts production deployment;
+  there is no second EBK-managed environment approval or wait timer. The approver may also be
+  the human whose merge triggers deployment. Roll back through a reviewed revert on the
+  protected branches and let the resulting \`main\` push redeploy. A repository write actor who
+  can run Actions may also manually dispatch \`deploy\`, \`refresh\`, or \`unlock\` against the
+  already approved \`main\` tip without another human gate. That residual cannot introduce
+  unreviewed source; production \`remove\` remains separately variable-gated. Restrict write and
+  Actions access, audit dispatches, or select \`environment-reviewer\` when every production
+  action needs separate approval.
+- \`environment-reviewer\` adds a separate production environment reviewer with self-review
+  prevention. A private repository needs GitHub Enterprise capability for this mode. Bootstrap
+  inspects that capability and fails closed on an unsupported plan; it never silently changes
+  the committed mode.
+
+Both modes retain required checks, a non-author CODEOWNER approval, no ruleset bypass, the
+literal production environment, and its branch-scoped credentials. Each environment owns its own
+\`AWS_DEPLOY_ROLE_ARN\`, \`AWS_EXPECTED_ACCOUNT_ID\`, and \`AWS_REGION\`; production also
+defines \`EBK_ALLOW_PRODUCTION_REMOVE\`, normally as \`false\`. Never add repository- or
+organization-visible fallbacks for these protected values. Keep repository default workflow
+permissions read-only; the generated jobs request only the additional permissions they need.
+
+Run the GitHub bootstrap in report mode first. Source upgrades never alter remote GitHub
+settings. Apply a reviewed report only after \`develop\` exists and the candidate's exact
+\`policy\` and \`verify\` check contexts have run.
+
+Set \`GH_REPO=<owner>/<repository>\` and a suitable \`GH_TOKEN\`, then run
+\`pnpm nx run ${name}:github-bootstrap\`. Review the deterministic report before rerunning
+with \`--apply\`. The command never creates branches, credentials, secrets, or AWS resources.
+Supply \`--productionReviewerIds=<id,...>\` only when committed policy selects
+\`environment-reviewer\`; it is rejected in \`promotion-pr\` mode.
+
+Install the optional defense-in-depth pre-push hook explicitly with
+\`pnpm nx run ${name}:install-git-hooks\`. It refuses to overwrite an unrelated existing hook.
+
+The sync-back workflow uses only \`GITHUB_TOKEN\` and never pushes or auto-merges. GitHub may
+place its pull-request workflows in an approval-required state. Approve them; if no run
+materializes, close and reopen the pull request as a human and then approve it.
+`,
+        'docs/repository-operating-policy.md': `# Repository Operating Policy
+
+\`ebk.repository-policy.json\` is the reviewed source of truth for production access,
+production approval, per-Slice readiness, and the one shared production Foundation profile.
+New workspaces start with production disabled and explicit Team-compatible
+\`productionApproval.mode: "promotion-pr"\`. A missing approval mode or Slice entry fails
+closed; no GitHub capability is allowed to choose a mode implicitly.
+
+The named repository modes are source-writing presets, not runtime state. Report a change
+first and inspect the complete current/next policy:
+
+\`\`\`bash
+pnpm nx g @empire-builder-kit/nx:repository-policy \\
+  --preset=controlled-production --slices=billing
+\`\`\`
+
+Apply the reviewed source change separately with \`--apply\`. This command never contacts AWS
+or GitHub. Use \`--status=blocked|pilot|ready\` for explicit Slice transitions and
+\`--profile=cost-optimized|standard\` for an explicit shared Foundation decision.
+Use \`--productionApprovalMode=promotion-pr|environment-reviewer\` for an explicit approval
+transition. This changes committed policy only; a separate bootstrap report/apply reconciles
+remote GitHub settings.
+
+Policies created before beta.7 do not contain \`productionApproval\`. After applying the
+workspace source upgrade, report the explicit amendment with
+\`pnpm nx g @empire-builder-kit/nx:repository-policy --productionApprovalMode=promotion-pr\`,
+review it, and rerun with \`--apply\` before health or bootstrap. This narrowly accepts a policy
+whose sole defect is the missing member; every other defect still fails closed. Validation
+provides no legacy default. Use \`promotion-pr\` for a private GitHub Team repository. Use
+\`environment-reviewer\` only when the repository plan can enforce a separate environment
+reviewer.
+
+- \`blocked\` prohibits production create, update, and migration.
+- \`pilot\` permits protected evidence gathering without claiming normal latency or maturity.
+- \`ready\` records an adopter decision after its evidence and review; it is not inferred.
+- removal and unlock remain explicit protected recovery paths so disabled policy cannot strand
+  resources.
+
+Protected production deploy and refresh validate the complete Foundation/Slice set before AWS
+access. The Foundation is always ordered first. The set is derived from committed policy and
+cannot be narrowed with an ad hoc project argument.
+
+\`standard\` keeps Aurora warm at 2–16 ACU. \`cost-optimized\` is a prerelease candidate at
+0–4 ACU with a five-minute auto-pause and potential cold-resume latency. Both keep managed NAT,
+30-day backups, deletion protection, retained data, and the protected GitHub/OIDC/AWS path.
+Changing policy affects only later lifecycle requests; it never deploys or removes resources.
+Changing profile requires a separate reviewed Foundation deployment and retained operational
+evidence.
+
+\`EBK_PRODUCTION_FOUNDATION_PROFILE\` is reserved managed executor input. The lifecycle
+executor derives it from validated committed policy immediately before SST and removes any
+ambient shell value. Do not set it as a local, repository, organization, or environment
+variable. Incubation keeps the last configured profile, or \`standard\` for legacy/default
+policy, solely so protected remove and unlock can still render existing production resources;
+production deploy remains disabled.
+`,
+        'docs/work-markers.md': `# Agent work markers
+
+EBK work markers let deterministic generators identify places where an agent or human must
+make a contextual product decision. They are searchable pointers to durable work, not a
+replacement for the referenced issue or plan.
+
+## Syntax and vocabulary
+
+Use one full-line source comment with a self-contained description. Examples include
+\`// EBK-TODO(GH:123): Replace the sample authorization decision with the approved policy.\`
+and
+\`# EBK-ASSUMPTION(PLAN:1/operator-proof): Confirm this timeout during the operator pilot.\`
+
+The fixed vocabulary is:
+
+- \`EBK-TODO\` — known implementation work;
+- \`EBK-ASSUMPTION\` — a decision that needs validation;
+- \`EBK-QUESTION\` — an unresolved design or product question;
+- \`EBK-SECURITY\` — security work that blocks protected promotion; and
+- \`EBK-BLOCKER\` — any other work that blocks protected promotion.
+
+Vocabulary names used in comment prose are inert. The scanner treats only a kind immediately
+followed by \`(\` or \`:\` as a marker attempt, so malformed marker-shaped comments still fail
+validation.
+
+Until Work Orchestration imports these markers, references must be an existing GitHub issue
+(\`GH:<positive-number>\`) or an append-only roadmap key
+(\`PLAN:<phase>/<slug>\`). The description must remain useful without opening the reference.
+The scanner validates syntax and ownership now; it intentionally does not claim that a
+reference exists. Phase 2 owns reference import, retained old-to-new ID mapping, and later
+orphan checks. Do not invent temporary Work Orchestration numbers.
+
+## Generator and agent workflow
+
+Generators may emit a marker only into a \`seeded\` customization surface. They must never put
+one in a \`managed\` file: managed output stays deterministic, and a needed change there is a
+framework defect to report outside the generated file. Adopter-owned files may also contain
+markers. Framework upgrades preserve seeded source and its unresolved markers.
+
+Blueprint and repository update tooling may create a deterministic reconciliation marker in a
+seeded or adopter-owned file when a preserved customization needs human or agent judgment. The
+update must preserve the custom code and identify the changed contract in the description; a
+successful update command alone does not resolve that marker. Reconcile the code, run the
+relevant checks, retain evidence at the referenced work item, and only then remove the marker.
+Automatic insertion requires an explicit publisher migration or other deterministic anchor;
+the generic upgrade command does not guess where to edit preserved custom code.
+
+At the start and handoff of agent work, run:
+
+\`pnpm nx run ${name}:work-markers\`
+
+The same ordinary validation runs through workspace health and CI. Complete the referenced
+custom work and remove the marker; do not merely delete it while leaving the requirement
+unresolved. Open \`TODO\`, \`ASSUMPTION\`, and \`QUESTION\` markers are reported but do not block
+deployment by themselves. Open \`SECURITY\` and \`BLOCKER\` markers fail staging and production
+deploy or refresh before AWS access. Protected remove and unlock remain usable for recovery.
+There is no local or silent bypass in this prerelease contract; any future waiver mechanism
+must be committed, reviewable, and auditable.
+`,
+        'ebk.repository-policy.json': json((0, index_js_3.createIncubationRepositoryPolicy)()),
         'nx.json': json({
             $schema: './node_modules/nx/schemas/nx-schema.json',
-            defaultBase: 'main',
+            defaultBase: 'develop',
             namedInputs: {
                 default: ['{projectRoot}/**/*', 'sharedGlobals'],
                 production: [
@@ -324,6 +815,13 @@ Foundation. Personal and preview consumer stages may use only the \`development\
             projectType: 'application',
             tags: ['scope:workspace', 'layer:governance'],
             targets: {
+                'deployment-plan': {
+                    executor: '@empire-builder-kit/nx:deployment-plan',
+                    options: {
+                        action: 'deploy',
+                        stage: 'staging',
+                    },
+                },
                 dev: {
                     continuous: true,
                     executor: '@empire-builder-kit/nx:fleet',
@@ -339,6 +837,18 @@ Foundation. Personal and preview consumer stages may use only the \`development\
                     executor: '@empire-builder-kit/nx:dev-setup',
                     options: {},
                 },
+                'github-bootstrap': {
+                    executor: '@empire-builder-kit/nx:github-bootstrap',
+                    options: {},
+                },
+                'install-git-hooks': {
+                    executor: 'nx:run-commands',
+                    options: { command: 'node tools/install-ebk-hooks.mjs' },
+                },
+                'work-markers': {
+                    executor: '@empire-builder-kit/nx:work-markers',
+                    options: {},
+                },
                 verify: {
                     executor: 'nx:run-commands',
                     options: { command: 'node tools/workspace-health.mjs' },
@@ -380,7 +890,13 @@ domain. Without it, the shared Router uses its functional provider URL.
             ],
         }),
         'packages/foundation/contracts/costs.json': json({
-            schemaVersion: 1,
+            schemaVersion: 2,
+            aurora: {
+                engine: index_js_3.FOUNDATION_AURORA_ENGINE_FAMILY,
+                engineVersion: index_js_3.FOUNDATION_AURORA_ENGINE_VERSION,
+            },
+            productionProfiles: index_js_3.PRODUCTION_FOUNDATION_PROFILE_CONTRACTS,
+            productionProfileSource: 'ebk.repository-policy.json',
             stages: {
                 development: {
                     aurora: 'scale-to-zero',
@@ -393,7 +909,7 @@ domain. Without it, the shared Router uses its functional provider URL.
                     nat: 'ec2',
                 },
                 production: {
-                    aurora: 'always-warm',
+                    aurora: 'repository-policy',
                     dataRetention: 'retained-and-protected',
                     nat: 'managed',
                 },
@@ -415,7 +931,9 @@ seeded decision record aligned with organization-specific budgets and alerts.
 
 - Development uses EC2 NAT, a development bastion, and Aurora scale-to-zero.
 - Staging uses EC2 NAT and Aurora scale-to-zero by default.
-- Production uses managed NAT and an always-warm Aurora baseline.
+- Production always uses managed NAT and retains protected data. Its explicit Repository
+  Operating Policy profile selects either the standard always-warm Aurora floor or the
+  prerelease cost-optimized auto-pause candidate.
 - ECS, EventBridge, Cognito, SNS, SSM, and CloudWatch are primarily usage-priced; logs,
   metrics, alarms, and retained data still require active cost review.
 
@@ -474,6 +992,11 @@ declare const $app: {
   foundationSsmPath,
   type FoundationSsmKey,
 } from '@empire-builder-kit/nx/foundation';
+import {
+  FOUNDATION_AURORA_ENGINE,
+  FOUNDATION_AURORA_ENGINE_VERSION,
+  productionFoundationProfileContract,
+} from '@empire-builder-kit/nx/repository-policy';
 
 function publishFoundation(values: Record<FoundationSsmKey, any>) {
   return Object.fromEntries(
@@ -492,11 +1015,16 @@ export function foundation() {
   const isProduction = $app.stage === 'production';
   const isStaging = $app.stage === 'staging';
   const rootDomain = process.env.EBK_ROOT_DOMAIN?.trim();
+  const productionConfiguration = isProduction
+    ? productionFoundationProfileContract(
+        process.env.EBK_PRODUCTION_FOUNDATION_PROFILE,
+      )
+    : undefined;
 
   const vpc = new sst.aws.Vpc('FoundationVpc', {
     az: 2,
     bastion: $app.stage === 'development',
-    nat: isProduction ? 'managed' : 'ec2',
+    nat: productionConfiguration?.contract.nat ?? 'ec2',
   });
   const cluster = new sst.aws.Cluster('FoundationCluster', { vpc });
   const router = new sst.aws.Router('FoundationRouter', {
@@ -512,16 +1040,19 @@ export function foundation() {
   });
   const database = new sst.aws.Aurora('FoundationDatabase', {
     dataApi: true,
-    engine: 'postgres',
-    scaling: isProduction
-      ? { min: '2 ACU', max: '16 ACU' }
-      : isStaging
+    engine: FOUNDATION_AURORA_ENGINE,
+    version: FOUNDATION_AURORA_ENGINE_VERSION,
+    scaling:
+      productionConfiguration?.contract.aurora ??
+      (isStaging
         ? { min: '0 ACU', max: '4 ACU', pauseAfter: '5 minutes' }
-        : { min: '0 ACU', max: '2 ACU', pauseAfter: '5 minutes' },
+        : { min: '0 ACU', max: '2 ACU', pauseAfter: '5 minutes' }),
     transform: {
       cluster: {
-        backupRetentionPeriod: isProduction ? 30 : 7,
-        deletionProtection: isProduction,
+        backupRetentionPeriod:
+          productionConfiguration?.contract.backupRetentionDays ?? 7,
+        deletionProtection:
+          productionConfiguration?.contract.deletionProtection ?? false,
       },
     },
     vpc,
@@ -531,9 +1062,39 @@ export function foundation() {
   });
   const eventBus = new sst.aws.Bus('FoundationEventBus');
   const alertTopic = new sst.aws.SnsTopic('FoundationAlerts');
+  const alertTopicPolicy = new aws.sns.TopicPolicy(
+    'FoundationAlertTopicPolicy',
+    {
+      arn: alertTopic.arn,
+      policy: aws.iam.getPolicyDocumentOutput({
+        statements: [
+          {
+            actions: ['sns:Publish'],
+            principals: [
+              { identifiers: ['events.rds.amazonaws.com'], type: 'Service' },
+            ],
+            resources: [alertTopic.arn],
+          },
+        ],
+      }).json,
+    },
+  );
+  const databaseInstanceId = database.nodes[0].identifier;
+  const databaseEvents = isProduction
+    ? new aws.rds.EventSubscription(
+        'FoundationDatabaseEvents',
+        {
+          eventCategories: ['failure', 'notification', 'serverless'],
+          snsTopic: alertTopic.arn,
+          sourceIds: database.nodes.map((node: any) => node.identifier),
+          sourceType: 'db-instance',
+        },
+        { dependsOn: [alertTopicPolicy] },
+      )
+    : undefined;
   const dashboard = new aws.cloudwatch.Dashboard('FoundationDashboard', {
     dashboardName: 'ebk-' + $app.stage + '-foundation',
-    dashboardBody: JSON.stringify({
+    dashboardBody: databaseInstanceId.apply((identifier: string) => JSON.stringify({
       widgets: [
         {
           type: 'text',
@@ -542,12 +1103,64 @@ export function foundation() {
           width: 24,
           height: 3,
           properties: {
-            markdown: '# Empire Builder Kit Foundation\\nStage: ' + $app.stage,
+            markdown:
+              '# Empire Builder Kit Foundation\\nStage: ' +
+              $app.stage +
+              '\\nProduction profile: ' +
+              (productionConfiguration?.profile ?? 'not-applicable'),
+          },
+        },
+        {
+          type: 'metric',
+          x: 0,
+          y: 3,
+          width: 12,
+          height: 6,
+          properties: {
+            title: 'Aurora capacity and pause state',
+            period: 60,
+            stat: 'Minimum',
+            metrics: [
+              ['AWS/RDS', 'ServerlessDatabaseCapacity', 'DBInstanceIdentifier', identifier],
+              ['.', 'ACUUtilization', '.', '.'],
+            ],
+          },
+        },
+        {
+          type: 'metric',
+          x: 12,
+          y: 3,
+          width: 12,
+          height: 6,
+          properties: {
+            title: 'Aurora connections',
+            period: 60,
+            stat: 'Maximum',
+            metrics: [
+              ['AWS/RDS', 'DatabaseConnections', 'DBInstanceIdentifier', identifier],
+            ],
           },
         },
       ],
-    }),
+    })),
   });
+  const databaseCapacityAlarm = new aws.cloudwatch.MetricAlarm(
+    'FoundationDatabaseCapacityAlarm',
+    {
+      alarmActions: [alertTopic.arn],
+      alarmDescription:
+        'Aurora Serverless capacity utilization stayed above 90 percent.',
+      comparisonOperator: 'GreaterThanThreshold',
+      dimensions: { DBInstanceIdentifier: databaseInstanceId },
+      evaluationPeriods: 5,
+      metricName: 'ACUUtilization',
+      namespace: 'AWS/RDS',
+      period: 60,
+      statistic: 'Average',
+      threshold: 90,
+      treatMissingData: 'notBreaching',
+    },
+  );
 
   if (new Set(['development', 'staging', 'production']).has($app.stage)) {
     new aws.cloudwatch.EventArchive('FoundationEventArchive', {
@@ -581,11 +1194,14 @@ export function foundation() {
     capabilities: STANDARD_FOUNDATION_CAPABILITIES,
     clusterId: cluster.id,
     contractVersion: '1.0.0',
+    databaseCapacityAlarmName: databaseCapacityAlarm.name,
     dashboardName: dashboard.dashboardName,
     databaseClusterId: database.id,
+    databaseEventSubscriptionId: databaseEvents?.id,
     eventBusName: eventBus.name,
     identityUserPoolId: userPool.id,
     name: 'foundation',
+    productionFoundationProfile: productionConfiguration?.profile,
     rootDomain,
     routerUrl: router.url,
     vpcId: vpc.id,
@@ -613,7 +1229,10 @@ export function foundation() {
             targets: {
                 deploy: {
                     executor: '@empire-builder-kit/nx:deploy',
-                    dependsOn: ['verify'],
+                    dependsOn: [
+                        'verify',
+                        { target: 'profile-preflight', params: 'forward' },
+                    ],
                     options: {
                         cwd: 'packages/foundation',
                         stage: 'development',
@@ -638,6 +1257,7 @@ export function foundation() {
                 },
                 refresh: {
                     executor: '@empire-builder-kit/nx:refresh',
+                    dependsOn: [{ target: 'profile-preflight', params: 'forward' }],
                     options: {
                         cwd: 'packages/foundation',
                         stage: 'development',
@@ -657,6 +1277,10 @@ export function foundation() {
                     executor: '@empire-builder-kit/nx:foundation-remove-preflight',
                     options: { stage: 'development' },
                 },
+                'profile-preflight': {
+                    executor: '@empire-builder-kit/nx:foundation-profile-preflight',
+                    options: { stage: 'development' },
+                },
                 typecheck: {
                     executor: 'nx:run-commands',
                     options: {
@@ -709,7 +1333,11 @@ if (JSON.stringify(descriptor.capabilities) !== JSON.stringify(expectedCapabilit
   throw new Error('Foundation capability descriptor does not match the v1 standard.');
 }
 if (
-  costs.schemaVersion !== 1 ||
+  costs.schemaVersion !== 2 ||
+  costs.aurora?.engineVersion !== '${index_js_3.FOUNDATION_AURORA_ENGINE_VERSION}' ||
+  costs.productionProfileSource !== 'ebk.repository-policy.json' ||
+  costs.productionProfiles?.standard?.aurora?.min !== '2 ACU' ||
+  costs.productionProfiles?.['cost-optimized']?.aurora?.min !== '0 ACU' ||
   !costs.stages?.development ||
   !costs.stages?.staging ||
   costs.stages?.production?.dataRetention !== 'retained-and-protected'
@@ -792,7 +1420,69 @@ export default $config({
             files: [],
             references: [],
         }),
-        'tools/workspace-health.mjs': `import { createHash } from 'node:crypto';
+        'tools/ebk-git-policy.mjs': `import { evaluateGitPolicy } from '@empire-builder-kit/nx/git-policy';
+import { spawnSync } from 'node:child_process';
+
+const git = (...args) => {
+  const result = spawnSync('git', args, { encoding: 'utf8', shell: false });
+  if (result.status !== 0) {
+    throw new Error('git ' + args.join(' ') + ' failed: ' + (result.stderr || result.stdout).trim());
+  }
+  return result.stdout.trim();
+};
+const isAncestor = (ancestor, descendant) =>
+  spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+    encoding: 'utf8',
+    shell: false,
+  }).status === 0;
+
+const eventName = process.env.GITHUB_EVENT_NAME;
+if (!['pull_request', 'push', 'workflow_dispatch'].includes(eventName)) {
+  throw new Error('Unsupported or missing GITHUB_EVENT_NAME; Git policy fails closed.');
+}
+
+const request = { eventName, ref: process.env.GITHUB_REF };
+if (eventName === 'pull_request' || eventName === 'push') {
+  git(
+    'fetch',
+    '--no-tags',
+    'origin',
+    'main:refs/remotes/origin/main',
+    'develop:refs/remotes/origin/develop',
+  );
+}
+if (eventName === 'pull_request') {
+  const baseRef = process.env.GITHUB_BASE_REF;
+  const headRef = process.env.GITHUB_HEAD_REF;
+  if (!baseRef || !headRef) {
+    throw new Error('Pull-request branch metadata is missing.');
+  }
+  Object.assign(request, {
+    baseIsAncestorOfHead: isAncestor('refs/remotes/origin/' + baseRef, 'HEAD'),
+    baseRef,
+    headRef,
+    mainIsAncestorOfDevelop: isAncestor(
+      'refs/remotes/origin/main',
+      'refs/remotes/origin/develop',
+    ),
+  });
+} else if (eventName === 'push') {
+  Object.assign(request, {
+    baseIsAncestorOfHead: isAncestor('refs/remotes/origin/develop', 'HEAD'),
+    mainIsAncestorOfDevelop: isAncestor(
+      'refs/remotes/origin/main',
+      'refs/remotes/origin/develop',
+    ),
+  });
+}
+
+const decision = evaluateGitPolicy(request);
+process.stdout.write(JSON.stringify(decision, null, 2) + '\\n');
+if (!decision.allowed) process.exitCode = 1;
+`,
+        'tools/workspace-health.mjs': `import { validateRepositoryOperatingPolicy } from '@empire-builder-kit/nx/repository-policy';
+import { assertWorkMarkerReport, formatWorkMarkerReport, scanWorkMarkers } from '@empire-builder-kit/nx/work-markers';
+import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
@@ -853,6 +1543,14 @@ if (
 validateOwnership('.', workspace, 'Workspace');
 validateOwnership('packages/foundation', foundation, 'Foundation');
 
+const policy = validateRepositoryOperatingPolicy(readJson('ebk.repository-policy.json'));
+if (!policy.valid) {
+  throw new Error(
+    'Repository Operating Policy is invalid:\\n' +
+      policy.issues.map(({ message, path }) => '- ' + path + ': ' + message).join('\\n'),
+  );
+}
+
 for (const name of readdirSync('packages')) {
   if (name === 'foundation') continue;
   const ownershipPath = join('packages', name, '.ebk/ownership.json');
@@ -863,6 +1561,9 @@ for (const name of readdirSync('packages')) {
   }
   validateOwnership(join('packages', name), ownership, 'Product Slice ' + name);
 }
+const markerReport = scanWorkMarkers(process.cwd());
+process.stdout.write(formatWorkMarkerReport(markerReport) + '\\n');
+assertWorkMarkerReport(markerReport);
 process.stdout.write('Empire Builder Kit workspace source health is green.\\n');
 `,
     };