@open-mercato/cli 0.6.7 → 0.6.8-canary.320.1.bf889f49e4

package/dist/agentic/shared/ai/skills/tiers.json

@@ -3,30 +3,146 @@
   "default": ["core"],
   "external": {
     "source": "open-mercato/skills",
-    "description": "Skills installed from the shared open-mercato/skills collection via `npx skills add` (see scripts/install-skills.sh). Only the subset this standalone app ships is installed. A folder under .ai/skills/ matching one of these names is a repo-local override read by the external skill, never symlinked into the harness directories.",
+    "ref": "c6103c034571f3610323a1b53d97c81abe110b58",
+    "description": "Tier-selected delivery workflows installed at an exact tested collection commit. Same-name folders under .ai/skills are repo-local overrides and never replace these copies.",
+    "tiers": {
+      "core": {
+        "description": "Smallest dependency-closed set for daily standalone delivery.",
+        "skills": [
+          "om-spec-writing",
+          "om-code-review",
+          "om-integration-tests",
+          "om-prepare-test-env",
+          "om-auto-create-pr",
+          "om-auto-continue-pr",
+          "om-auto-review-pr",
+          "om-auto-implement-spec",
+          "om-auto-qa-pr",
+          "om-auto-fix-issue",
+          "om-verify-in-repo",
+          "om-root-cause",
+          "om-fix",
+          "om-open-pr",
+          "om-setup-agent-pipeline"
+        ]
+      },
+      "automation": {
+        "description": "Opt-in loop engines, issue authoring, and release-upgrade maintenance.",
+        "skills": [
+          "om-apply-upgrade-notes",
+          "om-auto-create-pr-loop",
+          "om-auto-continue-pr-loop",
+          "om-auto-write-spec",
+          "om-prepare-issue"
+        ]
+      }
+    },
     "skills": [
+      "om-spec-writing",
+      "om-code-review",
+      "om-integration-tests",
+      "om-prepare-test-env",
       "om-apply-upgrade-notes",
-      "om-auto-continue-pr",
-      "om-auto-continue-pr-loop",
       "om-auto-create-pr",
+      "om-auto-continue-pr",
       "om-auto-create-pr-loop",
-      "om-auto-fix-issue",
+      "om-auto-continue-pr-loop",
       "om-auto-review-pr",
-      "om-code-review",
-      "om-fix",
-      "om-integration-tests",
-      "om-open-pr",
+      "om-auto-implement-spec",
+      "om-auto-write-spec",
+      "om-auto-qa-pr",
+      "om-auto-fix-issue",
       "om-prepare-issue",
-      "om-prepare-test-env",
+      "om-verify-in-repo",
       "om-root-cause",
-      "om-setup-agent-pipeline",
-      "om-spec-writing",
-      "om-verify-in-repo"
-    ]
+      "om-fix",
+      "om-open-pr",
+      "om-setup-agent-pipeline"
+    ],
+    "dependencies": {
+      "om-spec-writing": [],
+      "om-code-review": ["om-setup-agent-pipeline"],
+      "om-integration-tests": ["om-prepare-test-env"],
+      "om-prepare-test-env": [],
+      "om-apply-upgrade-notes": ["om-setup-agent-pipeline"],
+      "om-auto-create-pr": ["om-auto-review-pr", "om-setup-agent-pipeline"],
+      "om-auto-continue-pr": ["om-auto-review-pr", "om-setup-agent-pipeline"],
+      "om-auto-create-pr-loop": [
+        "om-auto-continue-pr-loop",
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-continue-pr-loop": [
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-open-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-review-pr": ["om-code-review", "om-setup-agent-pipeline"],
+      "om-auto-implement-spec": [
+        "om-auto-create-pr",
+        "om-auto-continue-pr",
+        "om-auto-review-pr",
+        "om-auto-qa-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-qa-pr": [
+        "om-auto-review-pr",
+        "om-integration-tests",
+        "om-prepare-test-env",
+        "om-setup-agent-pipeline"
+      ],
+      "om-auto-write-spec": ["om-spec-writing", "om-open-pr", "om-setup-agent-pipeline"],
+      "om-auto-fix-issue": [
+        "om-auto-implement-spec",
+        "om-auto-qa-pr",
+        "om-auto-review-pr",
+        "om-verify-in-repo",
+        "om-root-cause",
+        "om-fix",
+        "om-open-pr",
+        "om-setup-agent-pipeline"
+      ],
+      "om-prepare-issue": [
+        "om-auto-write-spec",
+        "om-auto-fix-issue",
+        "om-auto-implement-spec",
+        "om-spec-writing",
+        "om-setup-agent-pipeline"
+      ],
+      "om-verify-in-repo": ["om-setup-agent-pipeline"],
+      "om-root-cause": ["om-setup-agent-pipeline"],
+      "om-fix": ["om-setup-agent-pipeline"],
+      "om-open-pr": ["om-setup-agent-pipeline"],
+      "om-setup-agent-pipeline": []
+    },
+    "contentHashes": {
+      "om-spec-writing": "sha256:80d5def47ff844748b1c7407cae8b8ee8588ccdfaee54022e15de885d59fa398",
+      "om-code-review": "sha256:f4503da210e6e5eb7d79a0972d3922a2888d8aed93e98a1bb73091c0dc2a750e",
+      "om-integration-tests": "sha256:a1385dbb9fe11fe8c7a16dbe8576e44b9e03f34254e5575955d5a6ea862ee741",
+      "om-prepare-test-env": "sha256:ccfeb9accfffeaf35423576aacc08c9a6e3d3b07ecf8f72da694878fb3a571ab",
+      "om-apply-upgrade-notes": "sha256:15d4166a9229ebe15365ad3ef50919443478ef5f4c1f2e7cccbf1b8a61482d0d",
+      "om-auto-create-pr": "sha256:fe5a8ff632234c74cd1b948dfa2f69bf79683df067d3b8bc116d7a954d017138",
+      "om-auto-continue-pr": "sha256:ced195e0e571672188b34322a9c215df225a9a1822e1db27f6b864b01624e66e",
+      "om-auto-create-pr-loop": "sha256:0e7c015705a89e623c4f6865901121404feb1f443e0e096facb2a337ad9d33a5",
+      "om-auto-continue-pr-loop": "sha256:2997eb7cbf131e1b88abf05ad930e793675c3cd1db1fece18438ec21b327c6ef",
+      "om-auto-review-pr": "sha256:c05b3f45de9563faa0561a3a12129f4fda8bb1780f60d1cdcce7383e75e2d1c5",
+      "om-auto-implement-spec": "sha256:f5408771aa3765c9c8f2709f5d17247d9b8fef19fd2461c2fedf25c90bb8cda7",
+      "om-auto-write-spec": "sha256:b0d79e189fef7f5c03540becda01d933f5153e39276988f58f9c1dd81e9887f7",
+      "om-auto-qa-pr": "sha256:bff71bf4020a1e92b56a17f35f9c63c5f8f942e95048d5bbdf5589443c2cbda9",
+      "om-auto-fix-issue": "sha256:8ca990752fc1e73f2a70902d567b94da6c74b15f4e409410aa27ba09b1506521",
+      "om-prepare-issue": "sha256:07dd578b00902e65abb408e233688675cc92d6783af1a43257ebfd2d5be34663",
+      "om-verify-in-repo": "sha256:2fcf67187b129261aeb59b53c8058e95eb91c1f3c0314756ff5f432a34c43a62",
+      "om-root-cause": "sha256:7c14fd6388ff72c8bb058de905264899b7ee9797bb4985b1891ec2da0ec1c815",
+      "om-fix": "sha256:c9eb58f7834026c13f2533ae6fc4987d32a0e3cec1fd7b220b47d7154ee6e804",
+      "om-open-pr": "sha256:18ef43308dd3e5aff2099b38779cb7447ae26b754d31e18a0f49f857bafdcba7",
+      "om-setup-agent-pipeline": "sha256:6f906df68194af5ef4d40ccaf6f4335d44f45ddcffa6e1f36331291ac90377c8"
+    }
   },
   "tiers": {
     "core": {
-      "description": "Daily-driver standalone skills installed by default.",
+      "description": "Daily standalone architecture, implementation, extension, debugging, and harness-maintenance skills.",
       "skills": [
         "om-help",
         "om-implement-spec",
@@ -34,21 +150,27 @@
         "om-module-scaffold",
         "om-data-model-design",
         "om-system-extension",
+        "om-integration-builder",
+        "om-create-ai-agent",
+        "om-build-workflow",
         "om-troubleshooter",
+        "om-framework-context",
+        "om-evolve-harness",
+        "om-judge-agent-session",
+        "om-share-this-session",
         "om-eject-and-customize"
       ]
     },
     "automation": {
-      "description": "Module-management helpers. Opt-in.",
+      "description": "Optional advanced delivery workflows and module-footprint maintenance.",
       "skills": ["om-trim-unused-modules"]
     },
-    "infra": {
-      "description": "Rare, special-case skills.",
-      "skills": ["om-integration-builder"]
-    },
     "migration": {
-      "description": "One-shot, version-pinned migrations. Install only when needed.",
-      "skills": ["om-auto-upgrade-0.4.10-to-0.5.0"]
+      "description": "One-shot, version-pinned migrations. Install only for the named upgrade.",
+      "skills": [
+        "om-auto-upgrade-0.4.10-to-0.5.0",
+        "om-auto-upgrade-0.6.6-to-0.6.7"
+      ]
     }
   }
 }

package/dist/agentic/shared/ai/skills/tiers.schema.json

@@ -1,88 +1,100 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://open-mercato.dev/schemas/skills/tiers.schema.json",
-  "title": "Open Mercato skills tier manifest",
-  "description": "Manifest mapping skill folders under .ai/skills/ to install tiers consumed by scripts/install-skills.sh.",
+  "title": "Standalone Open Mercato skill manifest",
   "type": "object",
   "additionalProperties": false,
-  "required": ["default", "tiers"],
+  "required": ["default", "external", "tiers"],
   "properties": {
-    "$schema": {
-      "type": "string"
-    },
+    "$schema": { "type": "string" },
     "default": {
       "type": "array",
       "minItems": 1,
-      "items": {
-        "type": "string",
-        "minLength": 1
-      },
-      "description": "Tier names installed when install-skills.sh is invoked with no flags."
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/tierName" }
     },
     "agents": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Agent harness settings for install-skills.sh. Skills always install into the canonical .agents/skills/ directory; per-agent symlinks are created only for agents that cannot read it.",
       "properties": {
         "ignore": {
           "type": "array",
-          "description": "Agents whose directories install-skills.sh must never write. Overridden by --ignore-agents.",
-          "items": {
-            "type": "string",
-            "enum": ["claude-code", "codex", "cursor"]
-          }
+          "uniqueItems": true,
+          "items": { "enum": ["claude-code", "codex", "cursor"] }
         }
       }
     },
     "external": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["source", "skills"],
-      "description": "Skills owned by an external collection and installed via `npx skills add` instead of local symlinks. Folders under .ai/skills/ matching these names are repo-local overrides, not installable skills.",
+      "required": ["source", "ref", "tiers", "skills", "dependencies", "contentHashes"],
       "properties": {
-        "source": {
-          "type": "string",
-          "minLength": 1,
-          "description": "The skills package source, e.g. a GitHub owner/repo."
-        },
-        "description": {
-          "type": "string"
+        "source": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
+        "ref": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "description": { "type": "string" },
+        "tiers": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": { "$ref": "#/$defs/tierName" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["description", "skills"],
+            "properties": {
+              "description": { "type": "string", "minLength": 1 },
+              "skills": {
+                "type": "array",
+                "minItems": 1,
+                "uniqueItems": true,
+                "items": { "$ref": "#/$defs/skillName" }
+              }
+            }
+          }
         },
         "skills": {
           "type": "array",
           "minItems": 1,
-          "items": {
-            "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/skillName" }
+        },
+        "dependencies": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+          "additionalProperties": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/skillName" }
           }
+        },
+        "contentHashes": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+          "additionalProperties": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
         }
       }
     },
     "tiers": {
       "type": "object",
       "minProperties": 1,
-      "propertyNames": {
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
+      "propertyNames": { "pattern": "^[a-z][a-z0-9-]*$" },
       "additionalProperties": {
         "type": "object",
         "additionalProperties": false,
         "required": ["description", "skills"],
         "properties": {
-          "description": {
-            "type": "string",
-            "minLength": 1
-          },
+          "description": { "type": "string", "minLength": 1 },
           "skills": {
             "type": "array",
             "minItems": 1,
-            "items": {
-              "type": "string",
-              "pattern": "^[a-z0-9][a-z0-9._-]*$"
-            }
+            "uniqueItems": true,
+            "items": { "$ref": "#/$defs/skillName" }
           }
         }
       }
     }
+  },
+  "$defs": {
+    "skillName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "tierName": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
   }
 }

package/dist/agentic/shared/ai/specs/2026-08-06-reference-module-activation.md

@@ -0,0 +1,248 @@
+# Reference Module Activation
+
+**Date**: 2026-08-06
+**Status**: Draft
+
+> Shipped with the scaffold. This is the covering specification for turning on the two reference modules this app already contains in source: the canonical `example` module and the installed `design_system` gallery. Requests to enable the Todo demo, expose the design-system gallery, or build the first app capability on top of either one are covered here — amend this file instead of writing a second specification.
+
+## TLDR
+
+Every generated app ships `src/modules/example` in source and packs the installed design-system gallery, and registers neither. Activation is a deliberate, reversible app decision rather than a default, because an enabled reference module adds routes, navigation entries, migrations, seeds, ACL features, workers, and search indexes that a production app has not asked for. This specification owns that opt-in: what activation changes, who may see the activated surfaces, how the two modules stay independent of each other, and what has to be green before either one is enabled outside a development environment.
+
+## Problem Statement
+
+A new team reads `src/modules/example`, decides the Todo slice is close enough to the capability they need, and turns it on by adding it to `src/modules.ts`. Nothing warns them that the module was designed as a teaching reference: its ACL features grant a demo surface, its seeds create demo records, its migrations create tables the product will never use, and its navigation entries appear next to real ones. The design-system gallery has the same shape — it is genuinely useful to a design team and genuinely inappropriate as a customer-facing route. Without a written contract, each app rediscovers the consequences after the fact, usually in staging, and the resulting "turn it back off" work has to unpick migrations and seeded rows rather than a single registry line. This document exists so the decision is made once, with the consequences visible before the registry changes.
+
+## Overview and Success Measures
+
+- **Primary outcome:** a team can enable either reference module, or build on it, without discovering an unintended route, grant, or seeded record afterwards.
+- **Leading indicators:** the activation checklist below is completed in the pull request that changes `src/modules.ts`.
+- **Baseline:** both modules are source-present and runtime-absent in every preset shipped by `create-mercato-app`.
+- **Market / product reference:** the Open Mercato monorepo runs the same two modules enabled, which is why their source is trustworthy as a reference and misleading as a default.
+
+## Goals
+
+- **REQ-001** — Enabling `example` is a single reviewable registry change whose runtime consequences are enumerated in advance.
+- **REQ-002** — Enabling `design_system` exposes `/backend/design-system` only to holders of `design_system.view`, and never to an unauthenticated or customer-facing surface.
+- **REQ-003** — Neither reference module gains a runtime dependency on the other, in either direction, when one or both are enabled.
+- **REQ-004** — Deactivation is reversible: removing the registry entry removes every route, navigation entry, worker, and grant, leaving only the data the migrations created.
+
+## Non-goals
+
+- Copying either reference module into a new module ID. That is new-capability work: route it through `om-module-scaffold`, which reads this app's `src/modules/example` as read-only reference source.
+- Editing anything inside `src/modules/example`. The tree is immutable reference context; app behavior belongs in an app-owned module.
+- Shipping either module enabled by default in a preset. Presets stay source-present and runtime-absent.
+
+## Proposed Solution
+
+Activation is registration plus the generation and migration steps registration implies, in that order, followed by the grants that make the new surfaces reachable. The registry entry in `src/modules.ts` is the only switch; everything else is derived from it by `yarn generate`, so the review surface stays one line and the consequences stay mechanical. The two modules are registered independently: an app may want the gallery for its designers and no Todo demo at all, which is the common case, and the reverse holds while a team is learning the module contracts. Because activation creates database objects, the specification treats "enabled in development" and "enabled in a deployed environment" as two separate decisions with two separate exit gates.
+
+### Design Decisions and Alternatives
+
+| Decision | Rationale | Alternative considered | Why rejected / deferred |
+|---|---|---|---|
+| Registration is the single switch | Keeps the reviewable surface to one line and lets generation derive everything else | An `OM_EXAMPLE_ENABLED` environment flag | A flag leaves the module registered, so routes and grants exist even when the flag is off |
+| The two modules activate independently | A design team wants the gallery without the Todo demo far more often than both | One combined "reference modules" switch | Couples two unrelated decisions and creates a dependency edge the modules do not have |
+| Deactivation leaves migrated tables in place | Dropping tables on a registry change would be an unreviewable data loss | Reverting migrations automatically | Destroys data on a change that reads as configuration |
+
+## Domain Vocabulary and Business Rules
+
+| Term / invariant | Precise meaning or rule | Source of truth | Failure behavior |
+|---|---|---|---|
+| source-present | The module's files exist under `src/modules/` or in an installed package, and the module is not registered | the filesystem | no runtime effect of any kind |
+| activated | The module ID appears in `src/modules.ts` and generation has run | `src/modules.ts` | routes, nav, ACL, workers and migrations become live |
+| reference immutability | No app change may write under `src/modules/example` | this specification | the change belongs in an app-owned module instead |
+| module independence | `example` and `design_system` never import each other at runtime | import graph | a dependency edge in either direction is a defect |
+
+## Users, Permissions, and Scope
+
+| Actor | Allowed outcomes | Scope rule | Required feature IDs |
+|---|---|---|---|
+| developer | activate either module locally, read the example source | own workstation | none |
+| administrator | grant the activated features to a role | organization | `example.view`, `example.manage` |
+| designer | open the gallery once activated | organization | `design_system.view` |
+
+Trusted `tenantId` and `organizationId` come from the authenticated session as they do for every other module; activation introduces no new scope derivation. No activated reference surface performs a system-scope operation.
+
+## Reuse and Ownership Map
+
+| Capability | Reuse / extend / app-own | Existing module or new module | Integration seam | Why |
+|---|---|---|---|---|
+| Todo CRUD reference | reuse read-only | `example` | read the source, do not register it in production | it is a teaching surface, not a product capability |
+| Component gallery | reuse as-is | `design_system` | activate behind `design_system.view` | it is genuinely useful internally and inappropriate publicly |
+| First app capability | app-own | a new module | `om-module-scaffold` starting at `src/modules/example/README.md` | app behavior belongs to the app |
+
+## Architecture and Data Flow
+
+```text
+src/modules.ts -> yarn generate -> generated registries -> routes, nav, ACL, workers
+                                -> migrations           -> database objects
+                                -> setup hooks          -> role features, defaults, opt-in examples
+```
+
+- **Module boundaries:** the two reference modules own separate invariants and share no entity, event, or import.
+- **Extension points:** an app extends the activated example through the documented widget, enricher, and event seams rather than by editing it.
+- **Alternatives considered:** shipping the modules unregistered but with their routes pre-generated; rejected because generated output would then contradict the registry.
+- **Compatibility:** an app that never activates either module observes no behavior change from this specification.
+
+## User Journeys
+
+### Journey J-001 — Activate the gallery for the design team
+
+1. A designer asks for the component gallery.
+2. An administrator adds `design_system` to `src/modules.ts` and runs `yarn generate` and the migration step.
+3. `/backend/design-system` becomes reachable and appears in navigation for roles holding `design_system.view`.
+4. A user without the feature receives a permission denial rather than an empty page, and no navigation entry is rendered for them.
+
+### Journey J-002 — Learn the module contracts from the activated example
+
+1. A developer activates `example` on their workstation only.
+2. The Todo list, create and edit surfaces, the bulk operation and its progress reporting become available.
+3. The developer reads the capability-linked source files listed in `src/modules/example/references/surface-map.md`.
+4. The developer removes the registry entry before opening a pull request, and the surfaces disappear on the next generation.
+
+## UI and Interaction Contracts
+
+Both activated surfaces are shipped surfaces, so this specification adds no new page. It records their contracts so that a review can check them rather than rediscover them.
+
+| Surface / route | Purpose and primary actions | Data source / mutations | Closest installed reference | Canonical shell / components | Required states | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `/backend/todos` | list, create, edit, bulk complete | `/api/example/todos` | the module itself | `Page`, `PageBody`, `DataTable`, `CrudForm` | loading, empty, error, conflict, success, permission denied | REQ-001 |
+| `/backend/design-system` | browse component families and variants | packed gallery registry | the module itself | `Page`, `PageBody` | loading, empty, permission denied | REQ-002 |
+
+### UI architecture
+
+| Role | Navigation groups in order | Dashboard / injected widgets | Login-to-primary-task flow |
+|---|---|---|---|
+| administrator | Example → Todos | Todo summary widget when activated | login → Todos → create, two clicks |
+| designer | Design → Design system | none | login → Design system, one click |
+
+| Surface / widget | Empty state guidance and action | Responsive behavior | Keyboard / focus behavior |
+|---|---|---|---|
+| `/backend/todos` | localized empty state offering create | table collapses to stacked rows | focus order follows the table, dialogs submit on Cmd/Ctrl+Enter and cancel on Escape |
+| `/backend/design-system` | localized empty state when a family has no entry | grid reflows to one column | entries are reachable by keyboard and announce their family |
+
+## Data Models
+
+Activation creates the tables the reference modules' own migrations define; this specification introduces no entity of its own. The rule that matters for the decision is that those tables persist after deactivation.
+
+| Field | Type / nullability | Scope / index | Sensitive / encrypted | Lifecycle and validation |
+|---|---|---|---|---|
+| `tenant_id` / `organization_id` | UUID, required on every activated reference entity | composite scope indexes | no | trusted context only |
+| `updated_at` | timestamp, required | optimistic-lock version | no | updated on every edit |
+
+## API, Command, and Error Contracts
+
+| Method / command | Path / ID | Auth and feature gate | Input | Success response / event | Errors and concurrency | Requirement IDs |
+|---|---|---|---|---|---|---|
+| `GET` | `/api/example/todos` | auth + `example.view` | list query | `{ items, totalCount }` | 400/401/403 | REQ-001 |
+| `POST` | `/api/example/todos` | auth + `example.manage` | todo body | 201 + `example.todo.created` | 400/403/409 | REQ-001 |
+| `GET` | `/backend/design-system` | auth + `design_system.view` | none | rendered gallery | 401/403 | REQ-002 |
+
+Every activated route keeps its shipped contract; activation never changes a method, path, or gate. A route that is unreachable while the module is unregistered returns the framework's ordinary not-found response, which is the observable proof that registration is the switch.
+
+## Events, Jobs, Notifications, and Cross-Module Flows
+
+| Trigger | Producer | Consumer | Side effect | Retry / idempotency / audit behavior |
+|---|---|---|---|---|
+| `example.todo.created` | `example` | the module's own subscribers | index update, cache invalidation | idempotent, retried by the queue contract |
+| bulk completion request | `example` | the module's dispatch and batch workers | progress job with a reported lifecycle | one logical execution per idempotency key |
+
+While the module is unregistered none of these run, no subscriber is registered, and no worker is scheduled.
+
+## Security, Privacy, and Compliance
+
+- **Authorization:** both activated surfaces are feature-gated, never role-name gated.
+- **Tenant isolation:** every activated reference read and write filters on the trusted scope and fails closed.
+- **Sensitive data:** the example's encrypted fields stay encrypted at rest once activated, and the gallery holds no user data at all.
+- **Abuse and failure modes:** the risk this specification actually controls is an unintended public surface, which is why activation and grants are separate steps.
+
+## Integration Coverage
+
+Tests must be self-contained and map to real API and UI paths.
+
+| Test ID | Level | Setup / fixture | Actions | Assertions | Requirement IDs |
+|---|---|---|---|---|---|
+| TEST-001 | integration | a generated app with neither module registered | request both routes | both are absent, no navigation entry, no grant | REQ-001, REQ-002 |
+| TEST-002 | integration | a generated app with `example` registered | run generation and exercise the Todo list and create paths | the surfaces work and stay scoped to the tenant | REQ-001 |
+| TEST-003 | security | a generated app with `design_system` registered and a user lacking the feature | open the gallery route | permission denied, no navigation entry rendered | REQ-002 |
+| TEST-004 | integration | a generated app with both registered | inspect the import graph | no edge in either direction between the two modules | REQ-003 |
+
+## Implementation Phases
+
+Phases are dependency ordered. Only the current phase may enter implementation.
+
+### Phase 1 — Decide and activate in development only
+
+- **Depends on:** none
+- **Outcome:** the requested surfaces are reachable on a workstation and the consequences are recorded.
+- **Why this order / value delivered:** the consequences of activation are observable before anything is deployed.
+- **Deliverables:** the `src/modules.ts` entry, generated output, applied migrations, the completed activation checklist in the pull request.
+- **Requirements closed:** REQ-001, REQ-003
+- **Tests:** TEST-001, TEST-002, TEST-004
+- **Validation:** `yarn generate`, `yarn typecheck`, the focused integration tests above
+- **Exit gate:** the activated surfaces render in light and dark mode at narrow width, and deactivating restores the absent state.
+
+### Phase 2 — Grant the features and deploy
+
+- **Depends on:** Phase 1 exit gate
+- **Outcome:** the intended roles, and only those roles, reach the activated surfaces in a deployed environment.
+- **Why this order / value delivered:** grants are the step that makes a surface publicly consequential, so they follow a proven activation.
+- **Deliverables:** the role-feature grants and the deployment migration run.
+- **Requirements closed:** REQ-002, REQ-004
+- **Tests:** TEST-003
+- **Validation:** the configured validation gate
+- **Exit gate:** a user without the feature is denied, a user with it succeeds, and removing the registry entry removes the surface again.
+
+## Requirement Traceability
+
+| Requirement | Journey / surface | Data/API/event contracts | Phase | Tests | Acceptance criterion |
+|---|---|---|---|---|---|
+| REQ-001 | J-002, `/backend/todos` | `/api/example/todos`, `example.todo.created` | Phase 1 | TEST-001, TEST-002 | AC-001 |
+| REQ-002 | J-001, `/backend/design-system` | gallery route and `design_system.view` | Phase 2 | TEST-003 | AC-002 |
+| REQ-003 | both surfaces | import graph | Phase 1 | TEST-004 | AC-003 |
+| REQ-004 | both surfaces | registry entry | Phase 2 | TEST-001 | AC-004 |
+
+## Rollout, Migration, and Rollback
+
+Migrations are generated in the repository and applied by the deployment's own migration step, never by a developer running an ad-hoc apply against a shared database. Rollback is removal of the registry entry followed by generation; the tables the activated module created remain, and dropping them is a separate, deliberate data change.
+
+## Risks and Tradeoffs
+
+| Risk / tradeoff | Impact | Mitigation / detection | Residual risk |
+|---|---|---|---|
+| The example is mistaken for a product capability | demo surfaces reach real users | activation and grants are separate reviewed steps | a team may still grant deliberately |
+| Migrations run in a deployed environment before the decision is final | unused tables persist | Phase 1 proves the decision on a workstation first | tables remain after deactivation, by design |
+| A future app change edits the example in place | the reference stops matching the upstream tree | the tree is immutable context and reviews reject writes to it | none material |
+
+## Acceptance Criteria
+
+- [ ] **AC-001** — With `example` registered, an administrator creates and edits a Todo scoped to their organization; with it unregistered, the route is absent.
+- [ ] **AC-002** — With `design_system` registered, a user holding `design_system.view` opens the gallery and a user without it is denied.
+- [ ] **AC-003** — With both registered, no import edge exists between the two modules in either direction.
+- [ ] **AC-004** — Removing either registry entry and regenerating removes its routes, navigation entries, workers, and grants.
+
+## Final Compliance Report
+
+| Check | Status | Evidence / resolution |
+|---|---|---|
+| Applicable `AGENTS.md` files and routed guides/skills reviewed | pass | `AGENTS.md`, `.ai/guides/spec-delivery.md`, `.ai/skills/om-module-scaffold/SKILL.md` |
+| Data models, APIs, events, UI, and tests are internally consistent | pass | the traceability table above |
+| Every workflow completes end to end without a catch-all integration phase | pass | J-001 and J-002 each close in their own phase |
+| Platform-native reuse and extension points were chosen before custom code | pass | the reuse map keeps app behavior in an app-owned module |
+| UI contracts identify references, canonical components, and theme/state coverage | pass | the surface table above |
+| Every phase has dependencies, bounded slices, tests, value, and an observable exit gate | pass | Phase 1 and Phase 2 |
+
+Verdict: `Blocked — activation is an app decision this scaffold cannot make on the team's behalf`. Change the verdict and the status once the team has decided which modules to activate.
+
+## Open Questions
+
+| ID | Question | Owner | Blocking? | Resolution / decision date |
+|---|---|---|---|---|
+| Q-001 | Which reference modules does this app activate, in which environments? | the app team | yes | pending |
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-08-06 | Shipped with the scaffold as the covering specification for reference-module activation |

package/dist/agentic/shared/ai/specs/README.md

@@ -21,6 +21,7 @@ Example: 2026-03-01-inventory-module.md
 
 ## Workflow
 
-1. Before coding any significant feature, check for an existing spec
-2. If none: create from SPEC-000-template.md, review with team, then code
-3. After implementation: update the spec's Changelog and Acceptance Criteria
+1. Route every new application, multi-module feature, or non-trivial business slice through `om-spec-writing` and `.ai/guides/spec-delivery.md`.
+2. After invoking the skill, create the skeleton from `SPEC-000-template.md`; keep it `Draft` while blocking questions or incomplete contracts remain.
+3. Set `Ready for implementation` only after the final compliance report and requirement traceability pass and the user approves implementation.
+4. Implement through `om-implement-spec` (interactive local) or `om-auto-implement-spec` (whole-spec PR), one dependency-ordered phase at a time; update the Changelog, acceptance evidence, and phase state as work lands. Local delivery confirms its phase-derived plan before coding and ends with the stable `Spec:` reference without implying PR automation.