@macedon-technologies/batman 1.32.0 → 1.33.0

package/.jsii

@@ -97,7 +97,7 @@
   },
   "name": "@macedon-technologies/batman",
   "readme": {
-    "markdown": "# Platform Common Projen\n\nA baseline architecture template for new projects using Projen. This project provides a standardized foundation that includes both frontend and backend components with authentication.\n\n## Project Intention\n\nThis template serves as a starting point for new projects, providing:\n- Consistent project structure and configuration\n- Pre-configured development tooling\n- Integrated authentication system\n- Full-stack application foundation\n\n## Components Created\n\nThe BatmanProject generates:\n\n### Frontend\n- **React Application** - Modern React app with TypeScript\n- **Clerk Authentication** - Integrated user authentication and management\n- **Playwright e2e Testing** - `@playwright/test` + `@clerk/testing` devDeps, a `test:e2e` task, and a scaffolded `playwright.config.ts` + `e2e/` starter suite (see the generated `web/e2e/README.md`); disable with `e2eTesting: false`. The generated `pr-deploy.yml` workflow also runs this suite against each PR's deployed URL unless `e2eTesting: false` is set.\n\n### Backend/Infrastructure\n- **AWS Infrastructure** - CDK-based cloud resources\n- **API Gateway** - RESTful API endpoints\n- **Lambda Functions** - Serverless compute\n- **Database** - Persistent data storage\n\n## Usage Examples\n\n### Basic Project Creation\n\nCreate a `.projenrc.ts` file in your project root:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-new-app',\n  defaultReleaseBranch: 'main',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### With Custom Configuration\n\nCreate a `.projenrc.ts` file with additional options:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-enterprise-app',\n  defaultReleaseBranch: 'main',\n  description: 'Enterprise application with authentication',\n  authorName: 'Your Name',\n  authorEmail: 'your.email@company.com',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### Development Workflow\n\n```bash\n# Install dependencies\nyarn install\n\n# Start development server\nyarn dev\n\n# Deploy infrastructure\nyarn deploy\n\n# Run tests\nyarn test\n```\n\n## Deploying staging on demand\n\nThe generated `Staging Deploy` workflow runs on every push to `main` and can also be run manually from the Actions tab (\"Run workflow\"). Use that to redeploy `main` when a merge raised no push event or a deploy needs re-running. Pick `main` as the branch: the workflow deploys whichever branch you select.\n\n## Auto-merging pull requests with a GitHub App\n\nSetting `prAutoMerge: true` generates `.github/workflows/pr-auto-merge.yml`. It turns on GitHub's squash auto-merge for every pull request into the default branch when the pull request is opened, reopened or marked ready for review. Drafts and pull requests into other branches are left alone. The pull request then merges by itself once your branch ruleset is satisfied.\n\nThe workflow arms the merge with a GitHub App token, not `GITHUB_TOKEN`. GitHub attributes an auto-merge to whoever armed it and raises no events for anything `GITHUB_TOKEN` does, so a merge armed with it would never trigger `Staging Deploy` or `PR Cleanup`.\n\nThe App's private key can mint tokens for every repository the App is installed on, so it lives in an `auto-merge` environment that only `main` can use, not in the repository's secrets. Anyone with write access can read repository secrets from a workflow on their own branch. The workflow runs on `pull_request_target`, which uses the workflow file from the default branch and so passes the environment's branch rule; it never checks out pull request code. Use one App per repository so a leaked key reaches only that repository.\n\nSet it up in this order. Until the App and credentials exist, every pull request's `pr-auto-merge` run fails.\n\n1. **Create a GitHub App** in the organization (Settings → Developer settings → GitHub Apps → New GitHub App). It needs no webhook. Under Repository permissions give it **Read and write** on Contents, Pull requests, Workflows and Issues. Workflows is needed because Batman upgrades change files under `.github/workflows/`. Issues lets the merge close linked issues.\n2. **Generate a private key** on the App's page, and note its **Client ID**.\n3. **Install the App** on the repository (the App's page → Install App → Only select repositories).\n4. **Create an `auto-merge` environment** (Settings → Environments → New environment). Under Deployment branches and tags choose **Selected branches and tags** and add `main`. Then add to the environment:\n   - an environment **variable** `AUTO_MERGE_APP_CLIENT_ID` set to the Client ID;\n   - an environment **secret** `AUTO_MERGE_APP_PRIVATE_KEY` set to the full contents of the `.pem` file.\n\n   Don't add them as repository variables or secrets.\n5. **Turn on \"Allow auto-merge\"** in the repository's Settings → General → Pull Requests.\n6. **Protect the default branch** with a ruleset that requires an approving review and your required status checks. `prAutoMerge` doesn't create one. Without it, an armed pull request merges as soon as it can, unreviewed.\n7. Set `prAutoMerge: true` in `.projenrc.ts` and run projen.\n\nIf the variable or the secret is missing from the environment, the run fails with an error naming both. If the App's installation lacks one of the four permissions, minting the token fails. Pull requests from forks are armed like any other, since the workflow runs from the default branch, and still wait for the ruleset's review. Dependabot pull requests don't receive the environment's secret, so their runs fail the credential check. Merge those by hand. Each run also records a deployment to the `auto-merge` environment.\n\n## Upgrading\n\n### Datadog tracing defaults changed\n\n`BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:\n\n```ts\nprotected override createDatadogExtension() {\n  super.createDatadogExtension();\n  Object.assign(this.datadog.props, { enableMergeXrayTraces: true });\n}\n```\n\nNew projects' `src/constructs/Api.ts` installs `express` and `pg` into the Lambda artifact instead of bundling them, so dd-trace can trace router and `pg.query` calls. `Api.ts` is yours once generated, so existing projects add `express` and `pg` to `bundling.nodeModules` on the `NodejsFunction` in `createLambdaFunction()`, creating the block if it has none:\n\n```ts\nbundling: {\n  nodeModules: ['express', 'pg'],\n},\n```\n\nCDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.\n\n### The base stack no longer creates a VPC\n\n`BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.\nIt now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades\nwithout it deletes its VPC and NAT gateway on the next deploy.\n\nAdd `enableVpc: true` to every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts` (new projects: `additionalStackProps: { enableVpc: true }` on each environment) if any of these apply:\n\n- your `ApplicationStack` uses `this.vpc` or overrides `createVpc()`; the override is not called otherwise;\n- the Lambda reaches anything private, such as RDS or a VPC endpoint;\n- another stack imports this stack's VPC outputs; CloudFormation refuses to delete them.\n\n`this.vpc` is now typed `IVpc | undefined`, even with `enableVpc: true`, so code that passes it where an `IVpc` is required (such as `new SecurityGroup(this, 'Sg', { vpc: this.vpc })`) stops compiling. With `enableVpc: true` the VPC is created before your `ApplicationStack` constructor runs, so use `this.vpc!` there, or check it and throw if it's missing.\n\nOtherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;`) so the project compiles. Deleting the VPC can take a while as Lambda releases its network interfaces.\n\nWith `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.\n\n### n8n support is removed\n\n`BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.\n\nA project that doesn't use n8n stops compiling until it also removes:\n\n- `n8nEndpoint` from every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts`;\n- the `n8nEndpoint` prop, the n8n JWT key secret and its `grantRead` from `src/constructs/Api.ts`;\n- any `n8nEndpoint: this.props.n8nEndpoint` in a `createApi()` override;\n- any generated `src/constructs/*Workflow.ts` files and `src/workflows/`, which import the now-deleted `WorkflowProvider`.\n\nA project that uses n8n takes ownership of it:\n\n1. Upgrading makes projen delete `src/constructs/WorkflowProvider.ts`. Restore it from the last commit that had it, which works whether or not the deletion is already committed:\n\n   ```bash\n   git checkout \"$(git log -n1 --format=%H --diff-filter=AM -- src/constructs/WorkflowProvider.ts)\" -- src/constructs/WorkflowProvider.ts\n   ```\n\n   Then delete the `~~ Generated by projen` header line from it and from your per-workflow constructs (such as `AlfredWorkflow.ts`). They're yours from now on, and a new workflow needs its construct written by hand.\n2. Move `n8nEndpoint` from `Api` to your `ApplicationStack`. Remove the `n8nEndpoint` prop and its `N8N_ENDPOINT` environment entry from `src/constructs/Api.ts`, add `readonly n8nEndpoint: string;` to `ApplicationStackProps` (your `main.ts` and `LocalDevApp.ts` already pass it), and set the variable after `super()`:\n\n   ```typescript\n   this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);\n   ```\n\n## SoftwareFactoryFiles (standalone, non-Batman projects)\n\n`SoftwareFactoryFiles` is independently exported and can be attached to any\n`projen` `NodeProject` — it does not require `BatmanProject` or\n`BootcampProject`. It generates the `@swamp/software-factory` state machine,\nthe architecture rule registry, the pre-PR attestation gate, the OpenSpec\ntask-completion gate, and the swamp workflows that wire them together.\n\n```typescript\nimport { javascript } from 'projen';\nimport { SoftwareFactoryFiles } from '@macedon-technologies/batman';\n\nconst project = new javascript.NodeProject({\n  name: 'my-other-project',\n  defaultReleaseBranch: 'main',\n});\n\nnew SoftwareFactoryFiles(project, {\n  repoName: 'my-other-project',\n  githubOwner: 'my-github-org', // defaults to 'macedon-technologies' if omitted\n  baseBranch: 'main', // defaults to 'main'\n});\n\nproject.synth();\n```\n\nAfter running `npx projen`, follow the printed `swamp:bootstrap` task to pull\nthe required swamp extensions and create the project's secrets vault.\n\n### Work items and `factory/work-item-sources.md`\n\nA factory run's `workItem` is the ticket's bare key in its own tracker, such as\n`108` for a GitHub issue or `AI-123`, with nothing naming the tracker. The run's\nrecords and scratch paths are named after it, so a run is always started with\nthe bare key, even when the request names the tracker.\n\nThe factory's intake stage resolves the work item by following the managed\n`factory/work-item-sources.md`: which sources' key formats fit it, which model\nand method fetch it, how its fields map into the `issue-context` artifact, and\nwhich link line `open-pr` writes in the PR body (`Closes #<key>` for GitHub).\nWhen more than one source finds the key, intake stops and asks which was meant. Batman regenerates this file on every\nsynth, so supporting another tracker never needs a factory definition edit. The\nfile is part of the PR attestation manifest. The first synth that adds it changes\n`attestation/manifest.ts`, so any factory PR that's already open needs\nre-attesting.\n\n#### Updating an already-scaffolded factory\n\nThe factory definition (`models/@swamp/software-factory/<repo>-factory.yaml`)\nis written once, so a repo scaffolded before the routing file existed\nregenerates it:\n\n1. Note the file's `id:` line and any changes the repo has made to it since it\n   was scaffolded (`git log -p -- <file>`).\n2. Delete the file and run `npx projen`, which writes the current template.\n3. Put the old `id:` line back, so swamp still treats it as the same model, and\n   re-apply the repo's changes.\n\nRuns that recorded the old `issue-context` (`number` instead of `source`/`key`)\nkeep working: the routing file tells later stages to treat them as GitHub issues."
+    "markdown": "# Platform Common Projen\n\nA baseline architecture template for new projects using Projen. This project provides a standardized foundation that includes both frontend and backend components with authentication.\n\n## Project Intention\n\nThis template serves as a starting point for new projects, providing:\n- Consistent project structure and configuration\n- Pre-configured development tooling\n- Integrated authentication system\n- Full-stack application foundation\n\n## Components Created\n\nThe BatmanProject generates:\n\n### Frontend\n- **React Application** - Modern React app with TypeScript\n- **Clerk Authentication** - Integrated user authentication and management\n- **Playwright e2e Testing** - `@playwright/test` + `@clerk/testing` devDeps, a `test:e2e` task, and a scaffolded `playwright.config.ts` + `e2e/` starter suite (see the generated `web/e2e/README.md`); disable with `e2eTesting: false`. The generated `pr-deploy.yml` workflow also runs this suite against each PR's deployed URL unless `e2eTesting: false` is set.\n\n### Backend/Infrastructure\n- **AWS Infrastructure** - CDK-based cloud resources\n- **API Gateway** - RESTful API endpoints\n- **Lambda Functions** - Serverless compute\n- **Database** - Persistent data storage\n\n## Usage Examples\n\n### Basic Project Creation\n\nCreate a `.projenrc.ts` file in your project root:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-new-app',\n  defaultReleaseBranch: 'main',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### With Custom Configuration\n\nCreate a `.projenrc.ts` file with additional options:\n\n```typescript\nimport { BatmanProject } from '@macedon-technologies/batman';\n\nconst project = new BatmanProject({\n  name: 'my-enterprise-app',\n  defaultReleaseBranch: 'main',\n  description: 'Enterprise application with authentication',\n  authorName: 'Your Name',\n  authorEmail: 'your.email@company.com',\n});\n\nproject.synth();\n```\n\nThen run:\n```bash\nnpx projen\n```\n\n### Development Workflow\n\n```bash\n# Install dependencies\nyarn install\n\n# Start development server\nyarn dev\n\n# Deploy infrastructure\nyarn deploy\n\n# Run tests\nyarn test\n```\n\n## Deploying staging on demand\n\nThe generated `Staging Deploy` workflow runs on every push to `main` and can also be run manually from the Actions tab (\"Run workflow\"). Use that to redeploy `main` when a merge raised no push event or a deploy needs re-running. Pick `main` as the branch: the workflow deploys whichever branch you select.\n\n## Auto-merging pull requests with a GitHub App\n\nSetting `prAutoMerge: true` generates `.github/workflows/pr-auto-merge.yml`. It turns on GitHub's squash auto-merge for every pull request into the default branch when the pull request is opened, reopened or marked ready for review. Drafts and pull requests into other branches are left alone. The pull request then merges by itself once your branch ruleset is satisfied.\n\nThe workflow arms the merge with a GitHub App token, not `GITHUB_TOKEN`. GitHub attributes an auto-merge to whoever armed it and raises no events for anything `GITHUB_TOKEN` does, so a merge armed with it would never trigger `Staging Deploy` or `PR Cleanup`.\n\nThe App's private key can mint tokens for every repository the App is installed on, so it lives in an `auto-merge` environment that only `main` can use, not in the repository's secrets. Anyone with write access can read repository secrets from a workflow on their own branch. The workflow runs on `pull_request_target`, which uses the workflow file from the default branch and so passes the environment's branch rule; it never checks out pull request code. Use one App per repository so a leaked key reaches only that repository.\n\nSet it up in this order. Until the App and credentials exist, every pull request's `pr-auto-merge` run fails.\n\n1. **Create a GitHub App** in the organization (Settings → Developer settings → GitHub Apps → New GitHub App). It needs no webhook. Under Repository permissions give it **Read and write** on Contents, Pull requests, Workflows and Issues. Workflows is needed because Batman upgrades change files under `.github/workflows/`. Issues lets the merge close linked issues.\n2. **Generate a private key** on the App's page, and note its **Client ID**.\n3. **Install the App** on the repository (the App's page → Install App → Only select repositories).\n4. **Create an `auto-merge` environment** (Settings → Environments → New environment). Under Deployment branches and tags choose **Selected branches and tags** and add `main`. Then add to the environment:\n   - an environment **variable** `AUTO_MERGE_APP_CLIENT_ID` set to the Client ID;\n   - an environment **secret** `AUTO_MERGE_APP_PRIVATE_KEY` set to the full contents of the `.pem` file.\n\n   Don't add them as repository variables or secrets.\n5. **Turn on \"Allow auto-merge\"** in the repository's Settings → General → Pull Requests.\n6. **Protect the default branch** with a ruleset that requires an approving review and your required status checks. `prAutoMerge` doesn't create one. Without it, an armed pull request merges as soon as it can, unreviewed.\n7. Set `prAutoMerge: true` in `.projenrc.ts` and run projen.\n\nIf the variable or the secret is missing from the environment, the run fails with an error naming both. If the App's installation lacks one of the four permissions, minting the token fails. Pull requests from forks are armed like any other, since the workflow runs from the default branch, and still wait for the ruleset's review. Dependabot pull requests don't receive the environment's secret, so their runs fail the credential check. Merge those by hand. Each run also records a deployment to the `auto-merge` environment.\n\n## Upgrading\n\nEach note names the Batman release that introduced it. Read every note newer than the version you're upgrading from. A note is removed once every known Batman project is on that release or later.\n\n### Datadog tracing defaults changed (v1.32.0)\n\n`BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:\n\n```ts\nprotected override createDatadogExtension() {\n  super.createDatadogExtension();\n  Object.assign(this.datadog.props, { enableMergeXrayTraces: true });\n}\n```\n\nNew projects' `src/constructs/Api.ts` installs `express` and `pg` into the Lambda artifact instead of bundling them, so dd-trace can trace router and `pg.query` calls. `Api.ts` is yours once generated, so existing projects add `express` and `pg` to `bundling.nodeModules` on the `NodejsFunction` in `createLambdaFunction()`, creating the block if it has none:\n\n```ts\nbundling: {\n  nodeModules: ['express', 'pg'],\n},\n```\n\nCDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.\n\n### The base stack no longer creates a VPC (v1.30.0)\n\n`BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.\nIt now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades\nwithout it deletes its VPC and NAT gateway on the next deploy.\n\nAdd `enableVpc: true` to every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts` (new projects: `additionalStackProps: { enableVpc: true }` on each environment) if any of these apply:\n\n- your `ApplicationStack` uses `this.vpc` or overrides `createVpc()`; the override is not called otherwise;\n- the Lambda reaches anything private, such as RDS or a VPC endpoint;\n- another stack imports this stack's VPC outputs; CloudFormation refuses to delete them.\n\n`this.vpc` is now typed `IVpc | undefined`, even with `enableVpc: true`, so code that passes it where an `IVpc` is required (such as `new SecurityGroup(this, 'Sg', { vpc: this.vpc })`) stops compiling. With `enableVpc: true` the VPC is created before your `ApplicationStack` constructor runs, so use `this.vpc!` there, or check it and throw if it's missing.\n\nOtherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;`) so the project compiles. Deleting the VPC can take a while as Lambda releases its network interfaces.\n\nWith `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.\n\n### n8n support is removed (v1.30.0)\n\n`BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.\n\nA project that doesn't use n8n stops compiling until it also removes:\n\n- `n8nEndpoint` from every `ApplicationStack` in `src/main.ts` and `src/LocalDevApp.ts`;\n- the `n8nEndpoint` prop, the n8n JWT key secret and its `grantRead` from `src/constructs/Api.ts`;\n- any `n8nEndpoint: this.props.n8nEndpoint` in a `createApi()` override;\n- any generated `src/constructs/*Workflow.ts` files and `src/workflows/`, which import the now-deleted `WorkflowProvider`.\n\nA project that uses n8n takes ownership of it:\n\n1. Upgrading makes projen delete `src/constructs/WorkflowProvider.ts`. Restore it from the last commit that had it, which works whether or not the deletion is already committed:\n\n   ```bash\n   git checkout \"$(git log -n1 --format=%H --diff-filter=AM -- src/constructs/WorkflowProvider.ts)\" -- src/constructs/WorkflowProvider.ts\n   ```\n\n   Then delete the `~~ Generated by projen` header line from it and from your per-workflow constructs (such as `AlfredWorkflow.ts`). They're yours from now on, and a new workflow needs its construct written by hand.\n2. Move `n8nEndpoint` from `Api` to your `ApplicationStack`. Remove the `n8nEndpoint` prop and its `N8N_ENDPOINT` environment entry from `src/constructs/Api.ts`, add `readonly n8nEndpoint: string;` to `ApplicationStackProps` (your `main.ts` and `LocalDevApp.ts` already pass it), and set the variable after `super()`:\n\n   ```typescript\n   this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);\n   ```\n\n### `BaseService.ts` is no longer generated (v1.28.0)\n\n`ViteReactProject` no longer writes `web/src/services/BaseService.ts` or `web/src/services/RootService.ts`. `BaseService.ts` was managed, so upgrading makes projen delete it; `RootService.ts` was yours and stays. New projects get `web/src/services/ApiService.ts` and `web/src/helpers/` instead, and existing projects get them too wherever those files don't already exist.\n\nAnything that imports `BaseService.ts`, such as the old sample `App.tsx` or `RootService.ts`, stops compiling. Switch it to `useApiQuery` / `useApiMutation` from `ApiService.ts`, or keep your own copy of `BaseService.ts` by restoring it from the last commit that had it:\n\n```bash\ngit checkout \"$(git log -n1 --format=%H --diff-filter=AM -- web/src/services/BaseService.ts)\" -- web/src/services/BaseService.ts\n```\n\n## SoftwareFactoryFiles (standalone, non-Batman projects)\n\n`SoftwareFactoryFiles` is independently exported and can be attached to any\n`projen` `NodeProject` — it does not require `BatmanProject` or\n`BootcampProject`. It generates the `@swamp/software-factory` state machine,\nthe architecture rule registry, the pre-PR attestation gate, the OpenSpec\ntask-completion gate, and the swamp workflows that wire them together.\n\n```typescript\nimport { javascript } from 'projen';\nimport { SoftwareFactoryFiles } from '@macedon-technologies/batman';\n\nconst project = new javascript.NodeProject({\n  name: 'my-other-project',\n  defaultReleaseBranch: 'main',\n});\n\nnew SoftwareFactoryFiles(project, {\n  repoName: 'my-other-project',\n  githubOwner: 'my-github-org', // defaults to 'macedon-technologies' if omitted\n  baseBranch: 'main', // defaults to 'main'\n});\n\nproject.synth();\n```\n\nAfter running `npx projen`, follow the printed `swamp:bootstrap` task to pull\nthe required swamp extensions and create the project's secrets vault.\n\n### Work items and `factory/work-item-sources.md`\n\nA factory run's `workItem` is the ticket's bare key in its own tracker, such as\n`108` for a GitHub issue or `AI-123`, with nothing naming the tracker. The run's\nrecords and scratch paths are named after it, so a run is always started with\nthe bare key, even when the request names the tracker.\n\nThe factory's intake stage resolves the work item by following the managed\n`factory/work-item-sources.md`: which sources' key formats fit it, which model\nand method fetch it, how its fields map into the `issue-context` artifact, and\nwhich link line `open-pr` writes in the PR body (`Closes #<key>` for GitHub).\nWhen more than one source finds the key, intake stops and asks which was meant. Batman regenerates this file on every\nsynth, so supporting another tracker never needs a factory definition edit. The\nfile is part of the PR attestation manifest. The first synth that adds it changes\n`attestation/manifest.ts`, so any factory PR that's already open needs\nre-attesting.\n\n#### Updating an already-scaffolded factory\n\nThe factory definition (`models/@swamp/software-factory/<repo>-factory.yaml`)\nis written once, so a repo scaffolded before the routing file existed\nregenerates it:\n\n1. Note the file's `id:` line and any changes the repo has made to it since it\n   was scaffolded (`git log -p -- <file>`).\n2. Delete the file and run `npx projen`, which writes the current template.\n3. Put the old `id:` line back, so swamp still treats it as the same model, and\n   re-apply the repo's changes.\n\nRuns that recorded the old `issue-context` (`number` instead of `source`/`key`)\nkeep working: the routing file tells later stages to treat them as GitHub issues."
   },
   "repository": {
     "type": "git",
@@ -1393,6 +1393,6 @@
       "symbolId": "src/WorkflowActionVersions:WorkflowActionVersions"
     }
   },
-  "version": "1.32.0",
-  "fingerprint": "mzAhut3YlIggln/fITyEpqCI9pvzHMHbEObX8fjAVW4="
+  "version": "1.33.0",
+  "fingerprint": "cGijwamH3ea9tzt5nrOJYVxPV0QTXWy0gyYBQ2wuILk="
 }

package/README.md

@@ -116,7 +116,9 @@ If the variable or the secret is missing from the environment, the run fails wit
 
 ## Upgrading
 
-### Datadog tracing defaults changed
+Each note names the Batman release that introduced it. Read every note newer than the version you're upgrading from. A note is removed once every known Batman project is on that release or later.
+
+### Datadog tracing defaults changed (v1.32.0)
 
 `BaseApplicationStack` now defaults `datadog.nodeLayerVersion` to 143 (dd-trace 6.x) instead of 132, and passes `enableMergeXrayTraces: false` to `DatadogLambda`. These reach every project on its next `npx projen`. With merging off, the `aws.apigateway` span Datadog infers starts the API trace; API Gateway stage X-Ray tracing stays on. A stack that set its own `nodeLayerVersion` keeps it. To merge X-Ray traces again, override `createDatadogExtension()` in your `ApplicationStack`:
 
@@ -137,7 +139,7 @@ bundling: {
 
 CDK installs each package at the version spec in your root `package.json`, so `express` and `pg` must have plain version ranges there. A `catalog:` spec fails synth.
 
-### The base stack no longer creates a VPC
+### The base stack no longer creates a VPC (v1.30.0)
 
 `BaseApplicationStack` used to create a VPC with a NAT gateway and attach the API Lambda to it.
 It now creates neither unless the stack props set `enableVpc: true`. A stack that upgrades
@@ -155,7 +157,7 @@ Otherwise, make `vpc` optional in `src/constructs/Api.ts` (`readonly vpc?: IVpc;
 
 With `enableVpc: true`, the Lambda is attached only if your `Api.ts` still accepts a `vpc` prop and your stack doesn't override `createApi()` without passing it.
 
-### n8n support is removed
+### n8n support is removed (v1.30.0)
 
 `BatmanProject` and `BootcampProject` no longer generate any n8n wiring. The base stacks have no `n8nEndpoint` prop, `src/constructs/WorkflowProvider.ts` and a construct per `src/workflows/*.json` are no longer generated, and new projects get an `Api.ts`, `main.ts` and `LocalDevApp.ts` without n8n. The `n8nWorkflows` option, the `n8nEndpoint` environment config field and the exported `WorkflowAutoDiscover` class are gone, so every project removes `n8nWorkflows` and `n8nEndpoint` from its `.projenrc.ts`.
 
@@ -181,6 +183,16 @@ A project that uses n8n takes ownership of it:
    this.api.lambdaFunction.addEnvironment('N8N_ENDPOINT', props.n8nEndpoint);
    ```
 
+### `BaseService.ts` is no longer generated (v1.28.0)
+
+`ViteReactProject` no longer writes `web/src/services/BaseService.ts` or `web/src/services/RootService.ts`. `BaseService.ts` was managed, so upgrading makes projen delete it; `RootService.ts` was yours and stays. New projects get `web/src/services/ApiService.ts` and `web/src/helpers/` instead, and existing projects get them too wherever those files don't already exist.
+
+Anything that imports `BaseService.ts`, such as the old sample `App.tsx` or `RootService.ts`, stops compiling. Switch it to `useApiQuery` / `useApiMutation` from `ApiService.ts`, or keep your own copy of `BaseService.ts` by restoring it from the last commit that had it:
+
+```bash
+git checkout "$(git log -n1 --format=%H --diff-filter=AM -- web/src/services/BaseService.ts)" -- web/src/services/BaseService.ts
+```
+
 ## SoftwareFactoryFiles (standalone, non-Batman projects)
 
 `SoftwareFactoryFiles` is independently exported and can be attached to any

package/lib/BatmanProject.js

@@ -12,7 +12,7 @@ const SoftwareFactoryFiles_1 = require("./SoftwareFactoryFiles");
 const utils_1 = require("./utils");
 const ViteReactProject_1 = require("./ViteReactProject");
 class BatmanProject extends awscdk_1.AwsCdkTypeScriptApp {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BatmanProject", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BatmanProject", version: "1.33.0" };
     constructor(options) {
         super({
             ...options,

package/lib/BootcampProject.js

@@ -12,7 +12,7 @@ const SoftwareFactoryFiles_1 = require("./SoftwareFactoryFiles");
 const utils_1 = require("./utils");
 const ViteReactProject_1 = require("./ViteReactProject");
 class BootcampProject extends awscdk_1.AwsCdkTypeScriptApp {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BootcampProject", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.BootcampProject", version: "1.33.0" };
     constructor(options) {
         super({
             ...options,

package/lib/CodeOwnersFile.js

@@ -4,7 +4,7 @@ exports.CodeOwnersFile = void 0;
 const JSII_RTTI_SYMBOL_1 = Symbol.for("jsii.rtti");
 const projen_1 = require("projen");
 class CodeOwnersFile extends projen_1.TextFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.CodeOwnersFile", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.CodeOwnersFile", version: "1.33.0" };
     constructor(project, options = {}) {
         const defaultOwners = ['* @macedon-technologies/platform', '* @macedon-technologies/ai-development-team'];
         const allOwners = [...defaultOwners, ...(options.additionalOwners || [])];

package/lib/PrAutoMergeWorkflow.js

@@ -14,7 +14,7 @@ const PR_AUTO_MERGE_README_URL = 'https://github.com/macedon-technologies/platfo
  * workflows from pull request branches can't read the key. The job never checks out pull request code.
  */
 class PrAutoMergeWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.PrAutoMergeWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.PrAutoMergeWorkflow", version: "1.33.0" };
     constructor(project, options = {}) {
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);
         super(project, '.github/workflows/pr-auto-merge.yml', {

package/lib/ProductionDeployWorkflow.js

@@ -7,7 +7,7 @@ const javascript_1 = require("projen/lib/javascript");
 const utils_1 = require("./utils");
 const WorkflowActionVersions_1 = require("./WorkflowActionVersions");
 class ProductionDeployWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.ProductionDeployWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.ProductionDeployWorkflow", version: "1.33.0" };
     constructor(project, options) {
         const packageManager = project.package.packageManager;
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);

package/lib/SoftwareFactoryFiles.js

@@ -35,7 +35,7 @@ const DEFAULT_GITHUB_OWNER = 'macedon-technologies';
  * workflows that wire them together) is templated.
  */
 class SoftwareFactoryFiles {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.SoftwareFactoryFiles", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.SoftwareFactoryFiles", version: "1.33.0" };
     constructor(project, options) {
         const { repoName, actionVersions, attestationFiles } = options;
         const githubOwner = options.githubOwner || DEFAULT_GITHUB_OWNER;

package/lib/StagingDeployWorkflow.js

@@ -7,7 +7,7 @@ const javascript_1 = require("projen/lib/javascript");
 const utils_1 = require("./utils");
 const WorkflowActionVersions_1 = require("./WorkflowActionVersions");
 class StagingDeployWorkflow extends projen_1.YamlFile {
-    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.StagingDeployWorkflow", version: "1.32.0" };
+    static [JSII_RTTI_SYMBOL_1] = { fqn: "@macedon-technologies/batman.StagingDeployWorkflow", version: "1.33.0" };
     constructor(project, options) {
         const packageManager = project.package.packageManager;
         const actionVersions = (0, WorkflowActionVersions_1.resolveActionVersions)(options.actionVersions);

package/package.json

@@ -49,7 +49,7 @@
   "main": "lib/index.js",
   "license": "Apache-2.0",
   "stability": "stable",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "jest": {
     "coverageProvider": "v8",
     "testMatch": [
@@ -126,6 +126,7 @@
     "release": "projen release",
     "swamp:bootstrap": "projen swamp:bootstrap",
     "test": "projen test",
+    "test:templates": "projen test:templates",
     "test:watch": "projen test:watch",
     "unbump": "projen unbump",
     "upgrade": "projen upgrade",

package/templates/app/architecture-rules/README.md

@@ -0,0 +1,97 @@
+# Architecture rules
+
+A data-driven registry of architectural constraints, enforced by
+`pnpm validate:architecture` and run as part of the pre-PR verification
+workflow (`workflows/workflow-pre-pr-verify.yaml`) before the swamp factory
+opens a PR. New rules are new entries in `rules.json`, not new code — the
+engine (`check.ts`) only needs a new case in `evaluateRule()` when a rule
+needs a genuinely new kind of check.
+
+## Rule shape
+
+Two `check.type`s are implemented: `forbidden-import` (whole-repo import-graph
+check) and `required-companion` (diff-based co-change check).
+
+```json
+{
+  "id": "unique-id",
+  "description": "What this enforces and why.",
+  "enabled": true,
+  "severity": "low" | "medium" | "high" | "critical",
+  "check": {
+    "type": "forbidden-import",
+    "from": ["glob patterns selecting files this rule inspects"],
+    "forbid": ["glob patterns those files may not import from"]
+  }
+}
+```
+
+```json
+{
+  "id": "unique-id",
+  "description": "What this enforces and why.",
+  "enabled": true,
+  "severity": "low" | "medium" | "high" | "critical",
+  "check": {
+    "type": "required-companion",
+    "from": ["glob patterns selecting changed files that trigger the requirement"],
+    "requireOneOf": ["glob patterns -- at least one CHANGED file must match one of these"],
+    "exempt": ["optional -- from-files matching these globs don't trigger the requirement"]
+  }
+}
+```
+
+`required-companion` evaluates the set of files changed in the current diff
+(`git diff --name-only --diff-filter=ACMR <baseRef>...HEAD`), not the whole
+repo tree: if any changed file matches `from` (and doesn't match `exempt`) but
+no changed file matches `requireOneOf`, that's a violation. The base ref
+defaults to `origin/main` and can be overridden with the
+`ARCHITECTURE_RULES_BASE_REF` environment variable. This means the checkout
+running `pnpm validate:architecture` must have that base ref fetched and
+resolvable (a shallow, single-branch checkout will make the check fail closed
+with an error rather than silently reporting no violations) — make sure
+whatever runs this task fetches enough history for `git diff <baseRef>...HEAD`
+to succeed.
+
+`from`/`requireOneOf`/`exempt` globs are matched against the paths `git
+diff --name-only` reports, which are relative to the git repository's
+top-level directory. This lines up with `from`'s own directory (the parent of
+`architecture-rules/`) in the common case — a single project generated at the
+repo root — but if `architecture-rules/` instead lives under a nested
+subdirectory of a larger git repo, write globs relative to the git root, not
+to that subdirectory.
+
+**`required-companion` is a coverage check, not a correctness check.** It only
+confirms that *some* changed file matches `requireOneOf` — it can't tell
+whether that change is actually related to the triggering `from` change (a
+trivial or unrelated edit to a file under `requireOneOf` satisfies the rule
+just as well as a substantive one), and it can't tell whether a given `from`
+change genuinely needed a companion at all (a pure refactor might not).
+`exempt` covers *known, glob-expressible* exceptions, but not every false
+positive is expressible as a glob — that judgment call still belongs to the
+rule author (scoping `from`/`exempt`) and the reviewer (reading the companion
+diff, not just trusting that the check passed). Also note that `main()`
+fails the whole run on *any* violation regardless of `severity` — `severity`
+is informational only, not a leniency lever — so start with a narrowly
+scoped `from` (or `enabled: false`) and widen it as the convention proves
+itself, the same guidance as for `forbidden-import`.
+
+`enabled: false` rules are skipped (reported as "deferred") rather than
+evaluated — use this for a rule you've named and described but don't yet
+have a concrete convention to check.
+
+## Current rules
+
+None yet — `rules.json` ships empty. Add rules as your domain module
+conventions solidify (e.g. an event-sourced/CQRS module layout under
+`src/domains/<name>/{commands,events,aggregates,projections}/`).
+
+## Adding a check type
+
+`forbidden-import` (whole-repo import graph) and `required-companion`
+(diff-based co-change) are the implemented `check.type`s. If a future rule
+needs a data source neither provides (e.g. "every aggregate file must have a
+matching events file", which is a repo-wide naming convention rather than
+either an import-graph or a diff check), add a new `type` value, a matching
+interface, and a case in `evaluateRule()` in `check.ts` — keep the engine
+itself generic; rule-specific knowledge belongs in `rules.json`.

package/templates/app/architecture-rules/check.ts

@@ -0,0 +1,218 @@
+/**
+ * Generic architecture-rule engine. Rules live entirely in rules.json — this
+ * file only knows how to evaluate the check "types" that rules can declare.
+ * Add a new rule by adding a rules.json entry; add a new check type by adding
+ * a case in evaluateRule().
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import rulesFile from './rules.json';
+
+interface ForbiddenImportCheck {
+  type: 'forbidden-import';
+  // Glob patterns (relative to repo root) selecting the files this rule inspects.
+  from: string[];
+  // Glob patterns (relative to repo root) that "from" files may not import from.
+  forbid: string[];
+}
+
+interface RequiredCompanionCheck {
+  type: 'required-companion';
+  // Glob patterns selecting changed files that trigger the requirement.
+  from: string[];
+  // Glob patterns -- at least one CHANGED file must match one of these.
+  requireOneOf: string[];
+  // Optional -- 'from' files matching these globs don't trigger the requirement.
+  exempt?: string[];
+}
+
+interface Rule {
+  id: string;
+  description: string;
+  enabled: boolean;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+  check: ForbiddenImportCheck | RequiredCompanionCheck;
+}
+
+interface Violation {
+  ruleId: string;
+  severity: string;
+  message: string;
+}
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.swamp', 'cdk.out', 'lib', 'build', 'dist']);
+const BASE_REF = process.env.ARCHITECTURE_RULES_BASE_REF || 'origin/main';
+
+// Minimal glob -> RegExp: supports "*", "**", "**/" and literal path segments.
+// No new dependency for this — the only pattern shapes rules.json ever needs
+// are directory-prefix globs like "src/domains/*/commands/**".
+function globToRegExp(glob: string): RegExp {
+  let out = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      i++;
+      if (glob[i + 1] === '/') {
+        out += '(?:.*/)?';
+        i++;
+      } else {
+        out += '.*';
+      }
+    } else if (c === '*') {
+      out += '[^/]*';
+    } else if (c === '?') {
+      out += '[^/]';
+    } else if ('.+^${}()|[]\\'.includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`^${out}$`);
+}
+
+function matchesAny(relFile: string, globs: string[]): boolean {
+  return globs.some((glob) => globToRegExp(glob).test(relFile));
+}
+
+function toRepoRelative(absPath: string): string {
+  return path.relative(REPO_ROOT, absPath).split(path.sep).join('/');
+}
+
+// Files changed relative to baseRef, sourced from git rather than the whole-tree
+// walk() below -- required-companion checks care about what a PR touched, not
+// the full repo. Throws (rather than returning []) if baseRef cannot be resolved,
+// so an unfetched base ref fails the check instead of silently reporting no violations.
+function getChangedFiles(baseRef: string): string[] {
+  let output: string;
+  try {
+    output = execFileSync('git', ['diff', '--name-only', '--diff-filter=ACMR', `${baseRef}...HEAD`], {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    throw new Error(
+      `architecture-rules: failed to compute the changed-file set against base ref "${baseRef}" -- ` +
+        `is it fetched and resolvable in this checkout? (${(err as Error).message})`,
+    );
+  }
+  return output.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+}
+
+function walk(dir: string, acc: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(full, acc);
+    } else if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+const RELATIVE_IMPORT_RE = /(?:import|export)\s+(?:[^'";]*?\bfrom\s+)?['"](\.[^'"]+)['"]/g;
+
+function findRelativeImports(source: string): string[] {
+  const specs: string[] = [];
+  RELATIVE_IMPORT_RE.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = RELATIVE_IMPORT_RE.exec(source))) {
+    specs.push(match[1]);
+  }
+  return specs;
+}
+
+// An import spec resolves to a module, not a specific file extension, so a
+// forbid glob is checked against the bare resolved path plus its .ts/index.ts
+// variants.
+function resolvedCandidates(fromFile: string, spec: string): string[] {
+  const resolved = toRepoRelative(path.normalize(path.join(path.dirname(fromFile), spec)));
+  return [resolved, `${resolved}.ts`, `${resolved}/index.ts`];
+}
+
+function evaluateForbiddenImport(rule: Rule): Violation[] {
+  const { from, forbid } = rule.check as ForbiddenImportCheck;
+  if (from.length === 0 || forbid.length === 0) return [];
+
+  const violations: Violation[] = [];
+  for (const file of walk(REPO_ROOT)) {
+    const relFile = toRepoRelative(file);
+    if (!matchesAny(relFile, from)) continue;
+
+    const source = fs.readFileSync(file, 'utf8');
+    for (const spec of findRelativeImports(source)) {
+      const candidates = resolvedCandidates(file, spec);
+      if (candidates.some((candidate) => matchesAny(candidate, forbid))) {
+        violations.push({
+          ruleId: rule.id,
+          severity: rule.severity,
+          message: `${relFile} imports "${spec}", which resolves under a path forbidden by rule "${rule.id}"`,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+function evaluateRequiredCompanion(rule: Rule): Violation[] {
+  const { from, requireOneOf, exempt } = rule.check as RequiredCompanionCheck;
+  if (from.length === 0 || requireOneOf.length === 0) return [];
+
+  const changedFiles = getChangedFiles(BASE_REF);
+  const triggering = changedFiles.filter(
+    (file) => matchesAny(file, from) && !(exempt && matchesAny(file, exempt)),
+  );
+  if (triggering.length === 0) return [];
+
+  const satisfied = changedFiles.some((file) => matchesAny(file, requireOneOf));
+  if (satisfied) return [];
+
+  return [
+    {
+      ruleId: rule.id,
+      severity: rule.severity,
+      message: `changed file(s) ${triggering.join(', ')} match rule "${rule.id}"'s "from" patterns, but no changed file matches its "requireOneOf" patterns`,
+    },
+  ];
+}
+
+function evaluateRule(rule: Rule): Violation[] {
+  switch (rule.check.type) {
+    case 'forbidden-import':
+      return evaluateForbiddenImport(rule);
+    case 'required-companion':
+      return evaluateRequiredCompanion(rule);
+    default:
+      throw new Error(`architecture-rules: unknown check.type "${(rule.check as { type: string }).type}" on rule "${rule.id}"`);
+  }
+}
+
+function main(): number {
+  const rules = (rulesFile as { rules: Rule[] }).rules;
+  let evaluated = 0;
+  let deferred = 0;
+  const violations: Violation[] = [];
+
+  for (const rule of rules) {
+    if (!rule.enabled) {
+      deferred++;
+      console.log(`[deferred] ${rule.id}: ${rule.description}`);
+      continue;
+    }
+    evaluated++;
+    violations.push(...evaluateRule(rule));
+  }
+
+  console.log(`\narchitecture-rules: ${evaluated} rule(s) evaluated, ${deferred} deferred, ${violations.length} violation(s)`);
+  for (const violation of violations) {
+    console.error(`  [${violation.severity}] ${violation.ruleId}: ${violation.message}`);
+  }
+
+  return violations.length > 0 ? 1 : 0;
+}
+
+process.exit(main());

package/templates/app/architecture-rules/rules.json

@@ -0,0 +1,3 @@
+{
+  "rules": []
+}

package/templates/app/architecture-rules/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts",
+    "*.json"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/app/openspec-gates/check-tasks-complete.ts

@@ -0,0 +1,44 @@
+/**
+ * Gate: fails unless every task in the named OpenSpec change's tasks.md is
+ * checked off. `openspec validate`/`openspec status` don't check this (an
+ * in-progress change is a normal, valid state) — this is the deterministic
+ * check the pre-pr pipeline needs before letting implementation proceed.
+ */
+import { execFileSync } from 'node:child_process';
+
+interface OpenSpecChangeSummary {
+  name: string;
+  completedTasks: number;
+  totalTasks: number;
+  status: string;
+}
+
+function main(): number {
+  // pnpm's `-- <args>` forwarding (and projen's receiveArgs) can pass a
+  // literal "--" through as an argv token ahead of the real argument.
+  const slug = process.argv.slice(2).find((arg) => arg !== '--');
+  if (!slug) {
+    console.error('Usage: check-tasks-complete <change-slug>');
+    return 1;
+  }
+
+  const raw = execFileSync('openspec', ['list', '--json'], { encoding: 'utf8', shell: true });
+  const { changes } = JSON.parse(raw) as { changes: OpenSpecChangeSummary[] };
+  const change = changes.find((c) => c.name === slug);
+
+  if (!change) {
+    console.error(`OpenSpec change "${slug}" not found (openspec list --json)`);
+    return 1;
+  }
+  if (change.status !== 'complete') {
+    console.error(
+      `OpenSpec change "${slug}" has incomplete tasks: ${change.completedTasks}/${change.totalTasks}`,
+    );
+    return 1;
+  }
+
+  console.log(`OpenSpec change "${slug}": all ${change.totalTasks} tasks complete`);
+  return 0;
+}
+
+process.exit(main());

package/templates/app/openspec-gates/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}