@stacksjs/defaults 0.75.109 → 0.75.110

package/ai/skills/stacks-queue/SKILL.md

@@ -63,7 +63,7 @@ export class Job {
 2. `sync` driver: calls `dispatchNow()` (immediate execution)
 3. `redis` driver: creates `RedisQueue`, calls `queue.add()` with bun-queue options
 4. `database` driver: inserts into `jobs` table with JSON payload
-5. Fallback: `dispatchNow()`
+5. Unsupported/reserved or unknown drivers throw; they do not fall back to sync.
 
 ### dispatchNow() Execution Order
 1. If `handle` is a function: `await this.handle(payload)`
@@ -304,7 +304,7 @@ const wrappedHandler = withEvents('emails', originalHandler)
 
 ### OnQueueEvent Decorator
 Subscribes an **instance method** on `new`, with `this` bound to that instance.
-Declaring the class subscribes nothing, so the class has to be constructed — and
+Declaring the class subscribes nothing, so the class has to be constructed - and
 the instance has to stay referenced, because the global emitter holds listeners
 weakly (a collected listener stops receiving events).
 
@@ -322,7 +322,7 @@ getQueueEvents().unsubscribeListener(myHandler)
 ```
 
 Rejected with a `TypeError` at class-definition time: static methods, fields,
-accessors and whole classes (no instance to bind to — use `onQueueEvent(...)`),
+accessors and whole classes (no instance to bind to - use `onQueueEvent(...)`),
 and legacy `experimentalDecorators` decoration (no construction-time hook).
 
 ### Listener Introspection
@@ -421,7 +421,7 @@ await notifyJobFailed(jobInfo)           // uses global notifier
 ## Queue Testing (testing.ts)
 
 ```typescript
-import { fake, restore, runJob as runTestJob, expectJobToFail } from '@stacksjs/queue'
+import { fake, restore, runTestJob, expectJobToFail } from '@stacksjs/queue'
 
 const fakeQueue = fake()  // sets global FakeQueue singleton
 
@@ -467,6 +467,9 @@ tester.cleanup()  // calls restore()
 Wraps `bun-queue`'s `Queue` class with Stacks-compatible API.
 
 ```typescript
+import { getRedisQueue } from '@stacksjs/queue'
+
+const RedisQueue = await getRedisQueue()
 const queue = new RedisQueue<T>('emails', redisConfig)
 await queue.add(data, options)          // delay/attempts/priority/timeout/backoff
 queue.process(concurrency, handler)     // start processing (one-time call)
@@ -490,7 +493,13 @@ queue.getQueue(): BunQueue<T>           // underlying bun-queue instance
 queue.on(event, handler)                // subscribe to bun-queue events
 ```
 
-### StacksQueueManager
+### Internal driver manager
+
+`StacksQueueManager` lives inside the Redis driver and is not a named public
+package export. Prefer the public `QueueManager`/`getQueueManager` from the
+re-exported bun-queue surface, reading their own types before using them.
+The internal manager has this shape:
+
 ```typescript
 const manager = new StacksQueueManager(connectionConfigs)
 manager.queue('emails')     // get or create RedisQueue by name
@@ -539,7 +548,7 @@ await SendWelcomeEmail.dispatchNow({ email, name })        // bypass queue
 ## config/queue.ts
 ```typescript
 {
-  default: 'sync',  // 'sync' | 'database' | 'redis' | 'sqs' | 'memory'
+  default: 'sync',  // implemented dispatch drivers: sync | database | redis
   connections: {
     sync: { driver: 'sync' },
     database: { driver: 'database', table: 'jobs', queue: 'default', retryAfter: 90 },
@@ -585,3 +594,25 @@ await SendWelcomeEmail.dispatchNow({ email, name })        // bypass queue
 - `dispatchAfter()` on sync driver uses `setTimeout` to delay then executes immediately
 - Failed jobs table: `uuid`, `connection` ('database'), `queue`, `payload`, `exception` (stack trace), `failed_at`
 - `process.on('unhandledRejection')` and `process.on('uncaughtException')` are set at module load in worker.ts
+
+
+## Dispatch correctness and durable workflows
+
+Read [DURABLE-WORKFLOWS.md](DURABLE-WORKFLOWS.md) for transaction-aware dispatch,
+idempotency, payload serialization, trace/context propagation, persistent batch
+handlers, cooperative progress/cancellation and dead-letter handling.
+
+## Driver evidence
+
+Use `core/config/src/capabilities.ts` as the driver evidence source. Sync is
+inline and not durable. Database has a retained embedded SQLite worker contract;
+other SQL providers require separate queue evidence. Redis has a versioned core
+persistence contract, not a guarantee for every horizontal-scaling/distributed-
+lock option exposed by bun-queue. SQS, memory and beanstalkd are reserved and
+unsupported: dispatch fails loudly. Provisioning an SQS resource during cloud
+deployment does not implement this package's SQS dispatch driver.
+
+All public imports use `@stacksjs/queue`. The old bun-queue subpath does not
+have a complete published runtime entry. `Job` is Stacks' file-based Job;
+`BunJob` is the underlying bun-queue type. `fake()` affects the entire
+process; always call `restore()` in teardown.

package/ai/skills/stacks-realtime/SKILL.md

@@ -329,144 +329,22 @@ storeWebSocketEvent(type, socket, details): Promise<void> // no-op, kept for com
 
 ## config/realtime.ts
 
-Full configuration with all options and their defaults:
-
-```typescript
-export default {
-  enabled: true,
-
-  // Deployment mode
-  mode: 'server' as 'server' | 'serverless',
-  // 'server': ts-broadcasting (high-performance Bun WebSocket server)
-  // 'serverless': API Gateway WebSocket + Lambda + DynamoDB
-
-  // Legacy driver option (backward compat)
-  driver: 'bun' as 'socket' | 'pusher' | 'bun' | 'reverb' | 'ably',
-
-  // Server mode config (ts-broadcasting)
-  server: {
-    host: env.BROADCAST_HOST || '0.0.0.0',
-    port: Number(env.BROADCAST_PORT || 6001),
-    scheme: 'ws' as 'ws' | 'wss',
-    driver: 'bun',
-
-    redis: {
-      enabled: Boolean(env.BROADCAST_REDIS_ENABLED || false),
-      host: env.REDIS_HOST || 'localhost',
-      port: Number(env.REDIS_PORT || 6379),
-      password: env.REDIS_PASSWORD || '',
-      prefix: env.BROADCAST_REDIS_PREFIX || 'stacks:realtime:',
-    },
-
-    rateLimit: {
-      enabled: true,                    // env.BROADCAST_RATE_LIMIT_ENABLED
-      maxConnectionsPerIp: 100,
-      maxMessagesPerSecond: 50,
-      maxPayloadSize: 65536,            // 64KB
-      banDuration: 300,                 // seconds
-    },
-
-    loadManagement: {
-      maxConnections: 10000,
-      backpressureThreshold: 1000,
-      messageQueueSize: 10000,
-      gracefulShutdownTimeout: 30000,   // 30s
-    },
-
-    autoScaling: {
-      min: 1,
-      max: 10,
-      targetCPU: 70,                    // percentage
-    },
-
-    healthCheck: {
-      enabled: true,
-      path: '/health',
-      interval: 30,                     // seconds
-    },
-
-    metrics: {
-      enabled: Boolean(env.BROADCAST_METRICS_ENABLED || false),
-      port: 9090,
-      path: '/metrics',
-    },
-  },
-
-  // Serverless mode config (API Gateway WebSocket)
-  serverless: {
-    connectionTimeout: 3600,            // 1 hour
-    idleTimeout: 600,                   // 10 minutes
-    stageName: env.APP_ENV || 'production',
-    memorySize: 256,                    // MB
-    timeout: 30,                        // seconds
-  },
-
-  // Channel configuration
-  channels: {
-    public: true,
-    private: true,
-    presence: {
-      enabled: true,
-      maxMembersPerChannel: 100,
-      memberInfoTtl: 60,               // seconds
-    },
-  },
-
-  // App credentials (Pusher-compatible)
-  app: {
-    id: env.BROADCAST_APP_ID || 'stacks',
-    key: env.BROADCAST_APP_KEY || '',
-    secret: env.BROADCAST_APP_SECRET || '',
-  },
-
-  // Legacy socket config
-  socket: {
-    port: Number(env.BROADCAST_PORT || 6001),
-    host: env.BROADCAST_HOST || 'localhost',
-    cors: {
-      origin: env.BROADCAST_CORS_ORIGIN || env.APP_URL || 'http://localhost:3000',
-      methods: ['GET', 'POST'],
-    },
-  },
-
-  // Legacy Pusher config
-  pusher: {
-    appId: env.PUSHER_APP_ID || '',
-    key: env.PUSHER_APP_KEY || '',
-    secret: env.PUSHER_APP_SECRET || '',
-    cluster: env.PUSHER_APP_CLUSTER || 'mt1',
-    useTLS: Boolean(env.PUSHER_APP_USE_TLS ?? true),
-  },
-
-  debug: Boolean(env.BROADCAST_DEBUG || false),
-} satisfies RealtimeConfig
-```
-
-### Environment Variables
-| Variable | Default | Description |
-|---|---|---|
-| `REALTIME_MODE` | `server` | Deployment mode: server or serverless |
-| `BROADCAST_DRIVER` | `bun` | Broadcasting driver |
-| `BROADCAST_HOST` | `0.0.0.0` | Server bind host |
-| `BROADCAST_PORT` | `6001` | Server port |
-| `BROADCAST_SCHEME` | `ws` | WebSocket scheme (ws/wss) |
-| `BROADCAST_REDIS_ENABLED` | `false` | Enable Redis adapter |
-| `REDIS_HOST` | `localhost` | Redis host |
-| `REDIS_PORT` | `6379` | Redis port |
-| `REDIS_PASSWORD` | (empty) | Redis password |
-| `BROADCAST_REDIS_PREFIX` | `stacks:realtime:` | Redis key prefix |
-| `BROADCAST_RATE_LIMIT_ENABLED` | `true` | Enable rate limiting |
-| `BROADCAST_METRICS_ENABLED` | `false` | Enable metrics endpoint |
-| `BROADCAST_APP_ID` | `stacks` | App ID |
-| `BROADCAST_APP_KEY` | (empty) | App key |
-| `BROADCAST_APP_SECRET` | (empty) | App secret |
-| `BROADCAST_CORS_ORIGIN` | APP_URL | CORS origin |
-| `BROADCAST_DEBUG` | `false` | Debug mode |
-| `PUSHER_APP_ID` | (empty) | Pusher app ID |
-| `PUSHER_APP_KEY` | (empty) | Pusher app key |
-| `PUSHER_APP_SECRET` | (empty) | Pusher app secret |
-| `PUSHER_APP_CLUSTER` | `mt1` | Pusher cluster |
-| `PUSHER_APP_USE_TLS` | `true` | Pusher TLS |
+Read the application file for host/port, app credentials, channel and provider
+settings. The Stacks public server is explicitly created through createServer
+with ts-broadcasting ServerConfig, including authorizeConnection, websocket and
+endpoint options. A config field is applied only when the chosen runtime passes
+it to that server or deployment layer.
+
+Legacy pusher/ably/reverb/socket names, serverless definitions, Redis topology and
+auto-scaling settings are not separate proved application broadcasting drivers
+in the capability registry. Its retained Stacks topology is a single-process
+WebSocket server, requiring application fan-out to scale out. Do not pass the
+whole Stacks realtime config to createServer as if both types were identical.
+
+Environment values come from config/realtime.ts; browser clients receive only
+public connection configuration, never the secret. Connection auth and private
+channel authorizers apply independently. The HTTP application server has no
+automatic broadcast socket upgrade handler.
 
 ---
 
@@ -481,8 +359,19 @@ export default {
 - The `Broadcast` class is legacy -- new code should use `emit()` and `channel()` directly
 - There is no `handleWebSocketRequest()`: sockets upgraded on the app's own server were never part of the broadcast server, so they could not join channels. Clients connect to the broadcast server's `/ws`
 - There is no Stacks heartbeat or backpressure guard; use `createServer({ websocket: { idleTimeout, sendPings, backpressureLimit, closeOnBackpressureLimit } })`
-- Serverless mode uses API Gateway WebSocket for AWS Lambda with DynamoDB for connection management
+- Serverless/provider shapes in config describe cloud options; inspect their actual deploy/runtime wiring before claiming the Stacks broadcast APIs support that topology
 - Rate limiting defaults: 100 connections per IP, 50 messages/second, 64KB max payload, 300s ban duration
-- Redis adapter enables horizontal scaling across multiple server instances
+- The supported Stacks runtime contract is single-process WebSocket; scale-out requires an application-provided fan-out layer and separate provider evidence
 - Auto-scaling config (min/max/targetCPU) is for cloud deployment orchestration
 - The `satisfies RealtimeConfig` type annotation ensures the config matches the expected type from `@stacksjs/types`
+
+
+## Capability evidence
+
+`storage/framework/core/config/src/capabilities.ts` retains a single-process
+WebSocket contract. A redis/autoScaling/serverless config field is not proof that
+createServer wires it into the broadcast engine. Connection authorization and
+private/presence channel authorization are separate checks. Replay is in-memory
+and per process, not durable recovery or a cluster-wide sequence.
+Retained tests: `core/realtime/tests/ws-auth.test.ts`,
+`websocket-options.test.ts`, and replay/exclusion tests in that directory.

package/ai/skills/stacks-redesign/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 When applied to an existing Stacks project, follow this sequence:
 
-1. **Scan** - Read the codebase. Confirm the stack is stx + Crosswind + composables. Locate `resources/views/*.stx`, `resources/components/*.stx`, `resources/layouts/*.stx`, `config/ui.ts`, `config/crosswind.ts`, and the `fonts` config. Note current design patterns.
+1. **Scan** - Read the codebase. Confirm the stack is stx + Crosswind + composables. Locate `resources/views/*.stx`, `resources/components/*.stx`, `resources/layouts/*.stx`, `config/ui.ts`, `config/css.ts`, and the `fonts` config. Note current design patterns.
 2. **Diagnose** - Run through the audit below. List every generic pattern, weak point, and missing state you find.
 3. **Fix** - Apply targeted upgrades working with the existing stx + Crosswind stack. Do not rewrite from scratch and do not migrate frameworks. Improve what is there.
 

package/ai/skills/stacks-registry/SKILL.md

@@ -8,51 +8,23 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Registry
 
-## Key Paths
-- Core package: `storage/framework/core/registry/src/`
-- Config: `config/stacks.ts`
-- Package: `@stacksjs/registry`
-
-## Source Files
-```
-registry/src/
-└── index.ts              # Registry definition and exports
-```
-
-## API
-
-```typescript
-import { registry } from '@stacksjs/registry'
-import type { Registry } from '@stacksjs/registry'
-
-type Registry = StackExtensionRegistry
-
-const registry: Registry = [
-  {
-    name: 'stacks',
-    url: 'stacksjs.com',
-    github: 'stacksjs/stacks',
-  },
-]
-
-export default registry
-```
-
-The registry is a simple array of `StackExtensionRegistry` entries containing framework extension metadata — name, URL, and GitHub repository.
-
-## Usage
-
-```typescript
-import { registry } from '@stacksjs/registry'
-
-// Access extension metadata
-registry.forEach(ext => {
-  console.log(ext.name, ext.url, ext.github)
-})
-```
-
-## Gotchas
-- **Minimal package** — currently just a static array with the core Stacks framework entry
-- **Type comes from `@stacksjs/types`** — `StackExtensionRegistry` is defined in the types package
-- **Used for framework metadata** — not a package manager or dependency registry
-- **Config in `config/stacks.ts`** — the `StackExtensionRegistry` config is defined there
+`@stacksjs/registry` exports the named/default registry array and Registry type.
+The array derives from the central stackExtensionRegistry in `@stacksjs/types`,
+not from a hard-coded core Stacks URL entry or the app's installed dependencies.
+Each generated object carries name, github, optional package and description.
+
+Registry aliases StackExtensionRegistry, which also permits string shorthand
+names. Narrow an entry before accessing its object fields. config/stacks.ts is
+the application's extension configuration, separate from this known-extension
+catalog. A catalog entry does not mean that extension is installed.
+
+Use stacks-plugins for stack install/uninstall, package discovery, resource
+precedence and the lock/checksum contract. The central metadata links project-
+shaped GitHub source and optional npm package; discovery reads a package's actual
+stacks metadata. An umbrella extension can provide core and UI packages without
+manually copying all resources into app/.
+
+Source: `storage/framework/core/registry/src/index.ts` and
+`core/types/src/stack-extensions.ts`. Evidence:
+`core/registry/tests/registry.test.ts`. Read the registry at runtime rather than
+duplicating its entries or a fixed package count in documentation.

package/ai/skills/stacks-repl/SKILL.md

@@ -22,13 +22,13 @@ interface ReplConfig extends TinkerConfig {
   loadFile?: string  // Path to file to preload before starting
 }
 
-async function startRepl(config: ReplConfig): Promise<{ exitCode: number }>
+async function startRepl(config?: ReplConfig): Promise<{ exitCode: number }>
 ```
 
 ### How It Works
 1. If `config.loadFile` is specified, reads the file content
 2. Merges file content into `config.eval` for evaluation
-3. Starts an interactive Bun REPL session with all framework modules available
+3. Starts the Bun session; a nonempty eval/print selects non-interactive mode
 4. Returns the process exit code when the session ends
 
 ## Re-exports from @stacksjs/tinker
@@ -73,8 +73,32 @@ const email = faker.internet.email()
 ```
 
 ## Gotchas
-- **Tinker is the user-facing command, REPL is the engine** — `buddy tinker` calls `startRepl()` under the hood
-- **All framework imports available** — models, database, config, faker, etc. are preloaded
-- **History is persisted** — REPL history is saved to disk via `getHistoryPath()`
-- **File preloading** — use `loadFile` to run setup code before entering interactive mode
-- **Bun runtime** — the REPL runs in Bun's JavaScript runtime, not Node.js
+- **Tinker is the user-facing command, REPL is the engine** - `buddy tinker` calls `startRepl()` under the hood
+- **All framework imports available** - models, database, config, faker, etc. are preloaded
+- **History is persisted** - REPL history is saved to disk via `getHistoryPath()`
+- **File loading** - loadFile is composed into eval in the current wrapper and may select non-interactive mode; inspect that contract before expecting a prompt
+- **Bun runtime** - the REPL runs in Bun's JavaScript runtime, not Node.js
+
+
+## Native options and bootstrap limits
+
+ReplConfig also exposes bootstrap and showRoutes; startBunRepl delegates directly
+to startTinker. TinkerConfig supports eval/print, cwd, custom preload, history
+options and a banner setting. tinkerEval/tinkerPrint return the subprocess exit
+code, not the JavaScript expression's value. The configured database is real;
+REPL mutations are not automatically isolated test data.
+
+The current startRepl implementation combines loadFile/bootstrap/showRoutes
+into tinkerConfig.eval. startTinker treats nonempty eval as non-interactive,
+so do not promise those options perform setup and then leave a prompt open.
+Use a normal startRepl session and explicit imports when that behavior matters,
+or inspect the selected CLI wrapper before supplying an eval script.
+
+Preload globals are assembled by the REPL and may be absent when their import
+fails; this is a special interactive context, not the normal application's
+automatic-global list. History is persisted under getHistoryPath and defaults
+to .stacks_tinker_history in the home directory, with owner-only permissions
+when created. Avoid evaluating or retaining secrets in history.
+
+Source: `storage/framework/core/repl/src/index.ts` and core/tinker/src/index.ts.
+Tests: core/repl/tests/repl.test.ts and the tinker package's existing tests.

package/ai/skills/stacks-research/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-research/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## research
+
+Source: [skills/engineering/research/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/research/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Ported with Stacks skill names, canonical guidance, local-tracker fallback, TypeScript/Bun tooling, and conditional external actions.

package/ai/skills/stacks-research/PLAYBOOK.md

@@ -0,0 +1,10 @@
+> Adapted playbook. Read [the Stacks rules](../stacks-flow/ENGINEERING.md) first. Commit, push, publish, and tracker mutations are conditional on the user's authorization.
+
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

package/ai/skills/stacks-research/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: stacks-research
+description: Use when researching a question against primary sources, gathering API facts, or capturing cited findings for a Stacks design decision. Covers source verification and project research notes.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Research
+
+Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md), then
+[PLAYBOOK.md](PLAYBOOK.md). The playbook preserves this workflow's decision
+criteria; the Stacks rules govern APIs, tooling, tracking, and authorization.
+
+Credit: adapted from Matt Pocock's `research` skill, MIT licensed.
+See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+
+## Completion
+
+Produce the requested behavior or reviewable artifact and satisfy the
+playbook's completion criteria. Preserve existing decisions and user edits.
+Use the native Stacks skills for implementation and verification, and carry
+existing authorization through the workflow.

package/ai/skills/stacks-retro/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-retro/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## retro
+
+Source: [skills/engineering/retro/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/retro/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

package/ai/skills/stacks-retro/SKILL.md

@@ -30,6 +30,13 @@ logs on this machine. Work from what actually happened, not from a summary.
 
 ### Look for candidates in these categories
 
+Inspect the project's actual quality commands and CI before proposing a new
+check. An existing check that is unwired or broken is the finding to repair.
+Missing lint/typecheck/test enforcement in hooks and CI is a concrete gap.
+Mechanical mistakes belong in deterministic pickier rules or Bun checks;
+reserve prose standards for judgments tooling cannot enforce. Stay within the
+requested retrospective scope when proposing or applying improvements.
+
 - **Navigation.** How easy was it to find the right file? Are there hidden
   dependencies between files? Would a **navigation pointer** in `AGENTS.md`, or a
   `Key paths` block in the relevant skill, have shortened it? *Use when* the
@@ -73,6 +80,9 @@ Ask before writing any of them.
 
 ## Pass 2: the data
 
+Current upstream provenance is in [NOTICE.md](NOTICE.md). Read
+[the Stacks adaptation rules](../stacks-flow/ENGINEERING.md) with this workflow.
+
 Back the observations with git rather than impressions.
 
 ### Session detection

package/ai/skills/stacks-review/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-review/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## code-review
+
+Source: [skills/engineering/code-review/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/code-review/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.

package/ai/skills/stacks-review/SKILL.md

@@ -27,6 +27,11 @@ Matt Pocock's `code-review` skill (MIT), <https://github.com/mattpocock/skills>.
 
 ## 1. Pin the scope
 
+Resolve the requested ref with `git rev-parse` and confirm the selected diff is
+non-empty before starting either review axis. Capture the same diff command
+and commit list for both axes. Include `CODING_STANDARDS.md` and
+`CONTRIBUTING.md` when discovering the project's standards.
+
 1. If the user gives a PR number, branch, tag or commit, that is the fixed point.
    Diff with `git diff <fixed-point>...HEAD` (three dots, so the comparison is
    against the merge base) and list the commits with
@@ -58,6 +63,12 @@ reports "no spec available" and you review Standards only.
 
 ## 3. Run both axes
 
+Keep the Standards and Spec passes independent. When an invoked review uses
+subagents and the harness supports them, give each the same fixed diff and only
+its own relevant sources. Otherwise perform separate passes. Report findings
+under their own axes so a standards pass cannot hide a spec failure. A missing
+spec is reported explicitly rather than invented from the implementation.
+
 Both axes run as **parallel sub-agents** so they do not pollute each other's
 context, then this skill aggregates. Give each the diff command, the commit list,
 and its own brief.
@@ -239,5 +250,9 @@ prevent.
 
 ## Downstream
 
+Current upstream provenance is in [NOTICE.md](NOTICE.md); read
+[the Stacks adaptation rules](../stacks-flow/ENGINEERING.md) with this workflow.
+Use `stacks-pr` when writing the resulting PR description.
+
 > **Review complete.** Run `/stacks-browse` to QA in the browser, or
 > `/stacks-retro` to turn the findings into environment improvements.