create-agent-rig 0.3.2 → 0.5.0

package/templates/skeleton/aws-serverless/infra/test/app-stack.test.ts

@@ -1,38 +1,40 @@
 import { App } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
-import { beforeAll, describe, expect, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { AppStack } from '../lib/app-stack.js';
 
-// Template.fromStack bundles the Lambda entries with esbuild — slow-ish, run once.
-let template: Template;
-
-beforeAll(() => {
-  const app = new App();
-  template = Template.fromStack(new AppStack(app, 'TestStack'));
-});
+// `Template.fromStack` bundles the Lambda entries with esbuild — slow-ish, so
+// it runs once and is shared. Deliberately not in `beforeAll`: this project's
+// `vitest.config.ts` raises `testTimeout` for exactly this cost and leaves
+// `hookTimeout` at vitest's 10s default, so the same work in a hook runs on a
+// much shorter fuse — and it is contended, because sibling workers are
+// bundling too.
+let synthesised: Template | undefined;
+const template = (): Template =>
+  (synthesised ??= Template.fromStack(new AppStack(new App(), 'TestStack')));
 
 describe('storage', () => {
   it('creates the single table with pk/sk and on-demand billing', () => {
-    template.hasResourceProperties('AWS::DynamoDB::Table', {
+    template().hasResourceProperties('AWS::DynamoDB::Table', {
       KeySchema: [
         { AttributeName: 'pk', KeyType: 'HASH' },
         { AttributeName: 'sk', KeyType: 'RANGE' },
       ],
       BillingMode: 'PAY_PER_REQUEST',
     });
-    template.resourceCountIs('AWS::DynamoDB::Table', 1);
+    template().resourceCountIs('AWS::DynamoDB::Table', 1);
   });
 });
 
 describe('queue discipline', () => {
   it('wires the DLQ with maxReceiveCount 3', () => {
-    template.hasResourceProperties('AWS::SQS::Queue', {
+    template().hasResourceProperties('AWS::SQS::Queue', {
       RedrivePolicy: Match.objectLike({ maxReceiveCount: 3 }),
     });
   });
 
   it('alarms as soon as one message reaches the DLQ', () => {
-    template.hasResourceProperties('AWS::CloudWatch::Alarm', {
+    template().hasResourceProperties('AWS::CloudWatch::Alarm', {
       MetricName: 'ApproximateNumberOfMessagesVisible',
       Threshold: 1,
       EvaluationPeriods: 1,
@@ -41,7 +43,7 @@ describe('queue discipline', () => {
   });
 
   it('feeds the worker one message at a time', () => {
-    template.hasResourceProperties('AWS::Lambda::EventSourceMapping', {
+    template().hasResourceProperties('AWS::Lambda::EventSourceMapping', {
       BatchSize: 1,
     });
   });
@@ -49,11 +51,11 @@ describe('queue discipline', () => {
 
 describe('functions and routes', () => {
   it('deploys exactly the create, list and worker functions — one purpose each', () => {
-    template.resourceCountIs('AWS::Lambda::Function', 3);
+    template().resourceCountIs('AWS::Lambda::Function', 3);
   });
 
   it('passes table and queue to the api via environment', () => {
-    template.hasResourceProperties('AWS::Lambda::Function', {
+    template().hasResourceProperties('AWS::Lambda::Function', {
       Environment: {
         Variables: Match.objectLike({
           TABLE_NAME: Match.anyValue(),
@@ -64,27 +66,41 @@ describe('functions and routes', () => {
   });
 
   it('exposes exactly two routes: POST /notes and GET /notes', () => {
-    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Route', {
       RouteKey: 'POST /notes',
     });
-    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Route', {
       RouteKey: 'GET /notes',
     });
-    template.resourceCountIs('AWS::ApiGatewayV2::Route', 2);
+    template().resourceCountIs('AWS::ApiGatewayV2::Route', 2);
   });
 
   it('allows the browser origin in: CORS is configured', () => {
-    template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Api', {
       CorsConfiguration: Match.objectLike({
         AllowMethods: Match.arrayWith(['GET', 'POST']),
       }),
     });
   });
+
+  it('never allows every origin: the api names who may call it', () => {
+    const apis = template().findResources('AWS::ApiGatewayV2::Api');
+    const origins = Object.values(apis).flatMap(
+      (api) =>
+        (api.Properties as { CorsConfiguration?: { AllowOrigins?: unknown[] } }).CorsConfiguration
+          ?.AllowOrigins ?? [],
+    );
+
+    // A starter multiplies whatever it ships: `*` here becomes the default of
+    // every project generated from it. The web bundle has a known origin.
+    expect(origins.length).toBeGreaterThan(0);
+    expect(origins).not.toContain('*');
+  });
 });
 
 describe('least-privilege IAM', () => {
   it('grants writes to the creator, reads to the lister, queue send — nothing broad', () => {
-    const policies = template.findResources('AWS::IAM::Policy');
+    const policies = template().findResources('AWS::IAM::Policy');
     const statements = Object.values(policies).flatMap(
       (policy) =>
         (policy.Properties as { PolicyDocument: { Statement: Array<Record<string, unknown>> } })

package/templates/skeleton/aws-serverless/infra/test/web-stack.test.ts

@@ -1,20 +1,23 @@
 import { App } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
-import { beforeAll, describe, it } from 'vitest';
+import { describe, it } from 'vitest';
 import { WebStack } from '../lib/web-stack.js';
 
 // The web stack is stateless serving only: a private bucket behind CloudFront.
 // The bundle itself is synced by the deploy step (see README) — synth stays
 // independent of `next build`.
-let template: Template;
-
-beforeAll(() => {
-  template = Template.fromStack(new WebStack(new App(), 'TestWebStack'));
-});
+//
+// Synthesised lazily rather than in a `beforeAll`, like its neighbours in this
+// directory: `vitest.config.ts` raises `testTimeout` and leaves `hookTimeout`
+// at 10 s, so a hook is the one place in the suite running on a short fuse.
+// This stack bundles no Lambda and takes ~370 ms — the reason to do it anyway
+// is that the next person copies whatever shape is here.
+let cached: Template | undefined;
+const template = () => (cached ??= Template.fromStack(new WebStack(new App(), 'TestWebStack')));
 
 describe('web serving stack', () => {
   it('keeps the bucket fully private', () => {
-    template.hasResourceProperties('AWS::S3::Bucket', {
+    template().hasResourceProperties('AWS::S3::Bucket', {
       PublicAccessBlockConfiguration: Match.objectLike({
         BlockPublicAcls: true,
         BlockPublicPolicy: true,
@@ -25,9 +28,9 @@ describe('web serving stack', () => {
   });
 
   it('serves through CloudFront with origin access control', () => {
-    template.resourceCountIs('AWS::CloudFront::Distribution', 1);
-    template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
-    template.hasResourceProperties('AWS::CloudFront::Distribution', {
+    template().resourceCountIs('AWS::CloudFront::Distribution', 1);
+    template().resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
+    template().hasResourceProperties('AWS::CloudFront::Distribution', {
       DistributionConfig: Match.objectLike({
         DefaultRootObject: 'index.html',
       }),
@@ -35,7 +38,7 @@ describe('web serving stack', () => {
   });
 
   it('exports the distribution domain and bucket name for the deploy step', () => {
-    template.hasOutput('WebBucketName', {});
-    template.hasOutput('WebUrl', {});
+    template().hasOutput('WebBucketName', {});
+    template().hasOutput('WebUrl', {});
   });
 });

package/templates/skeleton/aws-serverless/services/api/src/handlers/create-note.ts

@@ -1,11 +1,19 @@
 // The handler translates transport ⇄ domain and nothing else: decode the
 // payload, call the usecase, map the result (or the typed error) to HTTP.
-import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
+import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context } from 'aws-lambda';
 import { InvalidNoteError } from '@app/core';
 import { AppError } from '@app/shared';
 import { createNoteUsecase, type CreateNoteDeps } from '../usecases/create-note.js';
 
-type Handler = (event: APIGatewayProxyEventV2) => Promise<APIGatewayProxyResultV2>;
+/**
+ * Lambda passes the context as the second argument; the handler takes the one
+ * field it needs, so a log line can be tied back to the invocation that wrote
+ * it. Optional because the context is Lambda's to supply, not the caller's.
+ */
+type Handler = (
+  event: APIGatewayProxyEventV2,
+  context?: Pick<Context, 'awsRequestId'>,
+) => Promise<APIGatewayProxyResultV2>;
 
 const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
   statusCode,
@@ -14,7 +22,7 @@ const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
 });
 
 export function makeCreateNoteHandler(deps: CreateNoteDeps): Handler {
-  return async (event) => {
+  return async (event, context) => {
     let payload: unknown;
     try {
       const raw = event.isBase64Encoded
@@ -32,11 +40,30 @@ export function makeCreateNoteHandler(deps: CreateNoteDeps): Handler {
       if (error instanceof InvalidNoteError) {
         return json(400, { error: 'invalid note', issues: error.issues });
       }
-      if (error instanceof AppError) {
+      // A 4xx message was written for the caller to read. A 5xx one was not:
+      // `AppError` defaults to 500/INTERNAL, so a table name, a host or an SDK
+      // message arrives here wearing the same type as "title is required".
+      // Typed does not mean safe to show — the status decides.
+      //
+      // The status itself is kept: 503 tells a caller to retry and 500 does
+      // not, and that distinction is transport, not disclosure. Only the
+      // message is withheld.
+      if (error instanceof AppError && error.statusCode < 500) {
         return json(error.statusCode, { error: error.message, code: error.code });
       }
-      deps.log.error('unhandled error in create-note', { error: String(error) });
-      return json(500, { error: 'internal error' });
+      // Everything past here is withheld, so it has to be kept somewhere: the
+      // message AND its frames, because a message with no stack is not
+      // something anyone can debug from a log aggregator, and the request id,
+      // because a line nobody can tie to an invocation is barely a line.
+      deps.log.error('unhandled error in create-note', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        // The one field of a withheld AppError worth keeping: it says WHICH
+        // internal failure this was, and it never reaches the caller.
+        code: error instanceof AppError ? error.code : undefined,
+        awsRequestId: context?.awsRequestId,
+      });
+      return json(error instanceof AppError ? error.statusCode : 500, { error: 'internal error' });
     }
   };
 }

package/templates/skeleton/aws-serverless/services/api/src/handlers/list-notes.ts

@@ -1,4 +1,4 @@
-import type { APIGatewayProxyResultV2 } from 'aws-lambda';
+import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context } from 'aws-lambda';
 import { AppError } from '@app/shared';
 import type { Logger } from '@app/shared';
 import { listNotesUsecase, type ListNotesDeps } from '../usecases/list-notes.js';
@@ -10,15 +10,28 @@ const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
 });
 
 export function makeListNotesHandler(deps: ListNotesDeps & { log: Logger }) {
-  return async (): Promise<APIGatewayProxyResultV2> => {
+  return async (
+    _event?: APIGatewayProxyEventV2,
+    context?: Pick<Context, 'awsRequestId'>,
+  ): Promise<APIGatewayProxyResultV2> => {
     try {
       return json(200, { notes: await listNotesUsecase(deps) });
     } catch (error) {
-      if (error instanceof AppError) {
+      // Same contract as create-note: a 4xx message was written for the caller,
+      // a 5xx one was not. The status survives — 503 tells a caller to retry
+      // and 500 does not — and only the message is withheld.
+      if (error instanceof AppError && error.statusCode < 500) {
         return json(error.statusCode, { error: error.message, code: error.code });
       }
-      deps.log.error('unhandled error in list-notes', { error: String(error) });
-      return json(500, { error: 'internal error' });
+      deps.log.error('unhandled error in list-notes', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        // The one field of a withheld AppError worth keeping: it says WHICH
+        // internal failure this was, and it never reaches the caller.
+        code: error instanceof AppError ? error.code : undefined,
+        awsRequestId: context?.awsRequestId,
+      });
+      return json(error instanceof AppError ? error.statusCode : 500, { error: 'internal error' });
     }
   };
 }

package/templates/skeleton/aws-serverless/services/api/src/usecases/create-note.ts

@@ -21,6 +21,17 @@ export interface CreateNoteDeps {
   log: Logger;
 }
 
+/**
+ * ⚠ These are **two writes and they are not atomic** — a dual write. The put
+ * can succeed and the publish then fail, which leaves a stored note whose event
+ * never happened: the worker does not run, nothing downstream hears about it,
+ * and nothing here compensates. The caller sees a 500 for a note that exists.
+ *
+ * That is a deliberate simplification for a skeleton, not a pattern to copy at
+ * scale. The two ways out, when it starts to matter: an **outbox** (write the
+ * event into the same transaction as the note, relay it after), or DynamoDB
+ * Streams feeding the worker, which removes the second write entirely.
+ */
 export async function createNoteUsecase(input: unknown, deps: CreateNoteDeps): Promise<Note> {
   const note = createNote(input, { id: deps.newId(), createdAt: deps.now() });
   await deps.notes.put(note);

package/templates/skeleton/aws-serverless/services/api/test/create-note.handler.test.ts

@@ -1,4 +1,8 @@
-import type { APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+  Context,
+} from 'aws-lambda';
 import { AppError, createLogger } from '@app/shared';
 import { describe, expect, it } from 'vitest';
 import { makeCreateNoteHandler } from '../src/handlers/create-note.js';
@@ -7,6 +11,9 @@ import type { CreateNoteDeps } from '../src/usecases/create-note.js';
 const event = (body: string): APIGatewayProxyEventV2 =>
   ({ body, isBase64Encoded: false }) as APIGatewayProxyEventV2;
 
+/** Lambda always passes a context; the handler only ever needs the request id. */
+const lambdaContext = (awsRequestId: string): Context => ({ awsRequestId }) as Context;
+
 function stubDeps(overrides: Partial<CreateNoteDeps> = {}) {
   const deps: CreateNoteDeps = {
     notes: { put: async () => {} },
@@ -89,4 +96,116 @@ describe('POST /notes handler', () => {
     expect(result.body).not.toContain('secret detail');
     expect(logs.join('\n')).toContain('secret detail');
   });
+
+  // AppError defaults to statusCode 500 / code INTERNAL, so "typed" does not
+  // mean "safe to show": a table name, a host, an SDK message all arrive this
+  // way. Only a 4xx AppError is a message the caller was meant to read.
+  it('hides a typed error that carries the default status behind the same constant 500', async () => {
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () => Promise.reject(new AppError('table NotesTable-prod is not authorised')),
+        },
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  // Withholding the message is not the same decision as flattening the status.
+  // 503 tells a caller to retry and 500 tells it not to bother, and that
+  // distinction is transport, not disclosure — the sibling handler pins it
+  // (`list-notes.test.ts`), and this one did not, so collapsing the status here
+  // passed the whole suite.
+  it('keeps a 5xx status the caller can act on, while still hiding the message', async () => {
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () =>
+            Promise.reject(
+              new AppError('table NotesTable-prod is throttling', {
+                statusCode: 503,
+                code: 'X',
+              }),
+            ),
+        },
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(result.statusCode).toBe(503);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('logs the typed internal error it hid, so the detail is kept and not lost', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () => Promise.reject(new AppError('table NotesTable-prod is not authorised')),
+        },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    await handler(event(JSON.stringify({ title: 'T' })));
+    expect(logs.join('\n')).toContain('NotesTable-prod');
+  });
+
+  it('logs the failure with its stack, not only its message', async () => {
+    const logs: string[] = [];
+    const boom = new Error('secret detail');
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: { put: () => Promise.reject(boom) },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    await handler(event(JSON.stringify({ title: 'T' })));
+    // `String(error)` is "Error: secret detail" — a message with no frames is
+    // not something anyone can debug from CloudWatch.
+    expect(JSON.parse(logs[0]!)).toMatchObject({ stack: boom.stack });
+  });
+
+  // The response withholds everything about a 5xx AppError, so the log line is
+  // the only place left that can say WHICH internal failure it was — and `code`
+  // is the one field of that error which is safe to keep verbatim. Losing it
+  // flattens DATA_CORRUPT, INTERNAL and every future code into one shape nobody
+  // can triage. The body assertion lives here on purpose: the two halves of the
+  // contract ("kept in the log", "still absent from the response") must not
+  // drift apart.
+  it('logs the code of the internal error it withheld, and still keeps it out of the response', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () =>
+            Promise.reject(
+              new AppError('table NotesTable-prod returned a torn item', {
+                code: 'DATA_CORRUPT',
+              }),
+            ),
+        },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ code: 'DATA_CORRUPT' });
+    expect(result.body).not.toContain('DATA_CORRUPT');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('carries the Lambda request id into the line it logs', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: { put: () => Promise.reject(new Error('secret detail')) },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    // Without it a log line cannot be tied to the invocation that produced it.
+    await handler(event(JSON.stringify({ title: 'T' })), lambdaContext('req-42'));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ awsRequestId: 'req-42' });
+  });
 });

package/templates/skeleton/aws-serverless/services/api/test/list-notes.test.ts

@@ -1,4 +1,8 @@
-import type { APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+  Context,
+} from 'aws-lambda';
 import { AppError, createLogger } from '@app/shared';
 import { describe, expect, it } from 'vitest';
 import { makeListNotesHandler } from '../src/handlers/list-notes.js';
@@ -14,6 +18,10 @@ const note = {
 
 const asResult = (r: unknown) => r as APIGatewayProxyStructuredResultV2;
 
+/** Lambda always passes the event and the context; this route needs no body. */
+const getEvent = () => ({ isBase64Encoded: false }) as APIGatewayProxyEventV2;
+const lambdaContext = (awsRequestId: string): Context => ({ awsRequestId }) as Context;
+
 describe('listNotesUsecase', () => {
   it('returns what the model lists', async () => {
     expect(await listNotesUsecase({ notes: { list: async () => [note] } })).toEqual([note]);
@@ -49,3 +57,66 @@ describe('GET /notes handler', () => {
     expect(logs.join('')).toContain('secret');
   });
 });
+
+// The same leak create-note was fixed for, and this handler had it too:
+// `AppError` defaults to 500/INTERNAL, so a table name, a host or an SDK
+// message arrives wearing the same type as "title is required", and every one
+// of them used to reach the caller. Typed does not mean safe to show — the
+// status decides, and these pin that both handlers decide it the same way.
+describe('GET /notes keeps its internals to itself', () => {
+  const failWith = (error: unknown, sink: (line: string) => void = () => {}) =>
+    makeListNotesHandler({
+      notes: { list: () => Promise.reject(error) },
+      log: createLogger({}, sink),
+    });
+
+  it('hides a typed error that carries the default status behind a constant 500', async () => {
+    const handler = failWith(new AppError('table NotesTable-prod is not authorised'));
+    const result = asResult(await handler(getEvent(), lambdaContext('req-1')));
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('still forwards a 4xx message, which was written for the caller to read', async () => {
+    const handler = failWith(new AppError('unknown tag filter', { statusCode: 400, code: 'BAD' }));
+    const result = asResult(await handler(getEvent(), lambdaContext('req-2')));
+    expect(result.statusCode).toBe(400);
+    expect(JSON.parse(result.body!)).toEqual({ error: 'unknown tag filter', code: 'BAD' });
+  });
+
+  it('logs the internal error it hid with its stack, so the detail is kept and not lost', async () => {
+    const logs: string[] = [];
+    const boom = new AppError('table NotesTable-prod is not authorised');
+    await failWith(boom, (line) => logs.push(line))(getEvent(), lambdaContext('req-3'));
+    // `String(error)` is a message with no frames — not something anyone can
+    // debug from a log aggregator.
+    expect(JSON.parse(logs[0]!)).toMatchObject({ stack: boom.stack });
+  });
+
+  // Same contract as create-note: the response withholds everything about a 5xx
+  // AppError, so the log line is the only place that can still say WHICH
+  // internal failure it was, and `code` is the one field safe to keep verbatim.
+  // The body assertion stays beside it so the two halves cannot drift apart.
+  it('logs the code of the internal error it withheld, and still keeps it out of the response', async () => {
+    const logs: string[] = [];
+    const handler = failWith(
+      new AppError('table NotesTable-prod returned a torn item', { code: 'DATA_CORRUPT' }),
+      (line) => logs.push(line),
+    );
+    const result = asResult(await handler(getEvent(), lambdaContext('req-4')));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ code: 'DATA_CORRUPT' });
+    expect(result.body).not.toContain('DATA_CORRUPT');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('carries the Lambda request id into the line it logs', async () => {
+    const logs: string[] = [];
+    const handler = failWith(new AppError('table NotesTable-prod is not authorised'), (line) =>
+      logs.push(line),
+    );
+    // Without it a log line cannot be tied to the invocation that produced it.
+    await handler(getEvent(), lambdaContext('req-42'));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ awsRequestId: 'req-42' });
+  });
+});

package/templates/skeleton/node-service/README.md

@@ -87,7 +87,17 @@ diagnose second.
   layer is mandatory even when it looks like ceremony.
 - `packages/core` is pure — the `guard-core-purity` hook refuses I/O, clock,
   randomness, and environment access at the tool layer.
-- `packages/db` is the only module that touches the stored data.
+- `packages/db` is the only module that touches the stored data. It is a
+  **single-instance store**: writes serialise inside one `JsonFileNoteStore`
+  object, and that is the whole of it. Two stores over the same file lose
+  notes to each other whether they sit in one process or two — share the one
+  instance, and reach for a real lock before you share the file.
+  A hard kill between the temp write and the rename leaves a `*.tmp` file
+  behind; nothing sweeps them.
+- `POST /notes` buffers at most **1 MB** of request body and answers `413` past
+  that. The cap lives in that route, not in the shell: a new route that reads a
+  body adds its own. Raise it in `services/api/src/server.ts` if your payloads
+  are bigger; do not remove it.
 - A failing queue message is poison: it throws, the spool retries ×3, then the
   DLQ gets it and the ALARM line fires. Never wrap the worker in a broad catch.
 

package/templates/skeleton/node-service/gitignore

@@ -9,10 +9,44 @@ out/
 next-env.d.ts
 dist/
 .claude/worktrees/
+# per-checkout queue state: the tier the last close recorded. The queue CONFIG
+# is composed and tracked; this is runtime state and must never be committed.
+.claude/queue.state.json
+# gate rounds, one count per branch
+.claude/gate-rounds.json
+# per-run machine trace (.claude/scripts/run-journal.mjs): forensics that churn
+# on every gate and collide across concurrent sessions. Unlike a committed
+# evidence directory, this one is per-run and stays out of the repository.
+.claude/runs/
 
 # secrets — never commit these
+*.env
 .env
 .env.*
 !.env.example
+.envrc
+.npmrc
+.netrc
+.pgpass
+id_rsa
+id_ed25519
 *.pem
 *.key
+*.p12
+*.pfx
+*.keystore
+*.jks
+*.secret
+*.secrets
+*.token
+*.tokens
+*.password
+*.passwords
+*.credential
+*.credentials
+*.apikey
+*.apikeys
+*.passwd
+*.creds
+*.jwt
+*.bearer