@open-mercato/cli 0.6.7-develop.6795.1.8a3f27921c → 0.6.7-develop.6824.1.21fff90682

package/dist/agentic/shared/ai/harness/RELEASE.md

@@ -6,7 +6,7 @@ Run the complete per-release gate from a generated standalone app with one comma
 yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
 ```
 
-Choose exactly one blocking primary runner with `--runner codex` or `--runner claude`. That runner owns the complete 202-case routing gate and every writable/review lane. To add cross-model portability evidence, explicitly pass the other runner as `--portability-runner claude` or `--portability-runner codex`; it runs only the exact 46-case representative read-only set. The two runners must differ. Omitting the portability option is valid and is recorded as `portabilityRunner: null`; no secondary result is claimed. There is no per-case fallback or mixed primary ownership. Once requested, a portability failure or unavailable runner fails that extended release run.
+Choose exactly one blocking primary runner with `--runner codex` or `--runner claude`. That runner owns the complete 203-case routing gate and every writable/review lane. To add cross-model portability evidence, explicitly pass the other runner as `--portability-runner claude` or `--portability-runner codex`; it runs only the exact 46-case representative read-only set. The two runners must differ. Omitting the portability option is valid and is recorded as `portabilityRunner: null`; no secondary result is claimed. There is no per-case fallback or mixed primary ownership. Once requested, a portability failure or unavailable runner fails that extended release run.
 
 `--prepare-targets` accepts only an absolute, new or empty regular directory outside the controller app. The controller must be a sanitized fresh scaffold: automatic preparation fails before copying when it finds `.env`, `.env.*` (except `.env.example`, `.env.sample`, and `.env.template`), credential files, or private-key files. Never use a configured development or production app as the controller. It copies the fresh scaffold once per catalog case whose `evaluationKind` is `implementation` or `regression`, while excluding `.git`, `node_modules`, build/cache/coverage output, `.ai/harness/results`, `.ai/reports`, and `.ai/framework-context`. Each target receives a guarded link to the controller's installed dependency tree. The OS sandbox resolves that link as read-only during both the writable model run and the target command gate. The release gate also hashes every dependency entry and regular-file body once before execution and once after the complete suite, and fails if any nested content or metadata changed. A generated `release-targets.json` records the local mapping.
 
@@ -34,17 +34,17 @@ For externally prepared apps, `--writable-targets /absolute/release-targets.json
 }
 ```
 
-The current catalog contains 202 cases, including 46 writable implementation/regression cases (22.8%). The command still derives all counts and case IDs from `cases.json`, `validators.json`, and `release-matrix.json`; those figures are documented release facts, not runner constants. The matrix keeps both supported runner model selectors, an exact all-case primary profile, an exact 46-case portability profile, and runner-neutral writable assignments. Run `yarn install-skills` first so the pinned external `om-code-review` skill and ownership evidence are present; the reusable local `om-judge-agent-session` skill ships with the scaffold. Before running a model or writing a fixture, the release command requires complete deterministic, primary live-routing, writable, trusted-oracle, target, generated-test, and generative-judge coverage. Every one of the 46 writable cases must have a judge assignment composing both skills. Missing business fixtures or release-matrix entries fail preflight and are listed by exact case ID in the report.
+The current catalog contains 203 cases, including 46 writable implementation/regression cases (22.7%). The command still derives all counts and case IDs from `cases.json`, `validators.json`, and `release-matrix.json`; those figures are documented release facts, not runner constants. The matrix keeps both supported runner model selectors, an exact all-case primary profile, an exact 46-case portability profile, and runner-neutral writable assignments. Run `yarn install-skills` first so the pinned external `om-code-review` skill and ownership evidence are present; the reusable local `om-judge-agent-session` skill ships with the scaffold. Before running a model or writing a fixture, the release command requires complete deterministic, primary live-routing, writable, trusted-oracle, target, generated-test, and generative-judge coverage. Every one of the 46 writable cases must have a judge assignment composing both skills. Missing business fixtures or release-matrix entries fail preflight and are listed by exact case ID in the report.
 
 ## PR #4529 remediation evidence
 
-The PR's focused remediation evidence is not a release-certification substitute. Fresh emitted controllers pass deterministic 192/192, and the field-tested OMH-188–192 generative cohort passes on default Codex, Claude Sonnet, and high-effort gpt-5.4-mini. Fresh OMH-185 writable attempts fixed concrete organization-scope, command-object, module-activation, command-snapshot, schema, custom-field, UI, and Jest guidance defects at their routed owners without relaxing trusted oracles. The final attempt reached the case's fixed 600-second ceiling and is excluded from pass evidence. Issue #4670 now owns the complete selected-primary 202-case routing and 46-case writable/generated-test/review certification, prioritizing the generative cohort and recording unavailable Claude lanes without fallback or mixed-runner ownership.
+The PR's focused remediation evidence is not a release-certification substitute. Fresh emitted controllers pass deterministic 192/192, and the field-tested OMH-188–192 generative cohort passes on default Codex, Claude Sonnet, and high-effort gpt-5.4-mini. Fresh OMH-185 writable attempts fixed concrete organization-scope, command-object, module-activation, command-snapshot, schema, custom-field, UI, and Jest guidance defects at their routed owners without relaxing trusted oracles. The final attempt reached the case's fixed 600-second ceiling and is excluded from pass evidence. Issue #4670 now owns the complete selected-primary 203-case routing and 46-case writable/generated-test/review certification, prioritizing the generative cohort and recording unavailable Claude lanes without fallback or mixed-runner ownership.
 
 After preflight it runs, in order:
 
 1. deterministic validation for the complete catalog;
 2. the release matrix's fixed `yarn generate`, `yarn typecheck`, `yarn lint`, and `yarn build` foundation;
-3. the selected primary runner across all 202 live-routing cases, followed by the optional distinct portability runner across the exact 46-case read-only sample when requested;
+3. the selected primary runner across all 203 live-routing cases, followed by the optional distinct portability runner across the exact 46-case read-only sample when requested;
 4. fixture preparation and the selected primary runner for every writable case, including the controller-owned AST/behavior oracles and target typecheck;
 5. `yarn generate`, `yarn typecheck`, `yarn lint`, and `yarn build` in every writable target, after its trusted oracles;
 6. real generated-code execution for OMH-163 and OMH-192 through fixed Jest, OMH-164 through API-only Playwright, and OMH-165 through real-browser Playwright; and

package/dist/agentic/shared/ai/harness/cases.json

@@ -1079,6 +1079,9 @@
         ".ai/guides/backend-ui.md",
         ".ai/skills/om-backend-ui-design/SKILL.md"
       ],
+      "allowedExtra": [
+        ".ai/guides/modules/design_system.md"
+      ],
       "warn": ["node_modules/@open-mercato/*/src/**"], "forbidden": [
         ".env*",
         ".git/**"
@@ -13583,5 +13586,95 @@
   {"id":"OMH-199","title":"Load a supplier spreadsheet in bulk without a hand-written parser","family":"architecture","mode":"analysis","evaluationKind":"routing","risk":"medium","prompt":"In a freshly scaffolded standalone Open Mercato app, a supplier sends a monthly spreadsheet and back-office staff retype several hundred rows by hand. They want to upload that file themselves and have the rows loaded, with a record of who uploaded what and whether the load succeeded. Decide the smallest safe design against what the installed modules already provide, keep tenant and organization boundaries intact, state the access-control posture for viewing an upload versus running one, and identify the smallest relevant validation. Do not write a bespoke spreadsheet parser or upload endpoint before establishing whether an installed module already owns this capability.","tags":["architecture","module-facts","reuse-installed","bulk-import"],"owner":{"kind":"facts","path":".ai/guides/modules/sync_excel.md","ruleIds":["BC-01","BC-04"]},"expectedRouter":{"required":["architecture"],"allowedExtra":["integration","module-data","framework-context","umes"]},"requiredSkills":["om-integration-builder"],"context":{"required":["AGENTS.md",".ai/guides/architecture.md",".ai/skills/om-integration-builder/SKILL.md",".ai/guides/modules/sync_excel.md"],"allowedExtra":[".ai/guides/integrations.md",".ai/guides/contracts.md",".ai/guides/modules/data_sync.md",".ai/skills/om-help/SKILL.md"],"warn":["node_modules/@open-mercato/*/src/**"],"forbidden":[".env*",".git/**"]},"requiredDecisions":["facts-first","tenant-scope","acl-features","smallest-validation"],"forbiddenPatterns":["node_modules.{0,40}(?:write|edit|patch)","(?:tenant|organization).{0,30}(?:unscoped|scope optional)"],"validators":["catalog.schema","owner.reference","skills.reference","router.contract","context.budget","context.forbidden","patterns.forbidden"],"maxContextFiles":11,"maxInitialContextBytes":57344,"maxTotalContextBytes":147456,"relatedCases":["OMH-002","OMH-195"]},
   {"id":"OMH-200","title":"Charge cards through the installed payment provider rather than a bespoke client","family":"architecture","mode":"analysis","evaluationKind":"routing","risk":"high","prompt":"In a freshly scaffolded standalone Open Mercato app, the business has a Stripe account and wants to start charging cards at checkout this week. Decide the smallest safe design against what the installed modules already provide, say where a payment provider belongs in a standalone app and how it is turned on for this one, state the access-control posture for viewing versus configuring it and how the provider credential is held, keep tenant and organization boundaries intact, and identify the smallest relevant validation. Do not write a bespoke provider client or a new payments module before establishing whether an installed module already owns this capability.","tags":["architecture","module-facts","reuse-installed","payment-provider"],"owner":{"kind":"facts","path":".ai/guides/modules/gateway_stripe.md","ruleIds":["BC-01","BC-04"]},"expectedRouter":{"required":["architecture"],"allowedExtra":["integration","module-data","framework-context","umes"]},"requiredSkills":["om-integration-builder"],"context":{"required":["AGENTS.md",".ai/guides/architecture.md",".ai/skills/om-integration-builder/SKILL.md",".ai/guides/modules/gateway_stripe.md"],"allowedExtra":[".ai/guides/integrations.md",".ai/guides/contracts.md",".ai/guides/modules/payment_gateways.md",".ai/skills/om-help/SKILL.md"],"warn":["node_modules/@open-mercato/*/src/**"],"forbidden":[".env*",".git/**"]},"requiredDecisions":["facts-first","app-module-activation","acl-features","smallest-validation"],"forbiddenPatterns":["node_modules.{0,40}(?:write|edit|patch)","(?:tenant|organization).{0,30}(?:unscoped|scope optional)"],"validators":["catalog.schema","owner.reference","skills.reference","router.contract","context.budget","context.forbidden","patterns.forbidden"],"maxContextFiles":11,"maxInitialContextBytes":57344,"maxTotalContextBytes":147456,"relatedCases":["OMH-002","OMH-195"]},
   {"id":"OMH-201","title":"Pull product data from the PIM the business already runs without a new connector","family":"architecture","mode":"analysis","evaluationKind":"routing","risk":"medium","prompt":"In a freshly scaffolded standalone Open Mercato app, the merchandising team maintains product data in Akeneo and wants it to reach this application on a schedule instead of being copied over by hand. Decide the smallest safe design against what the installed modules already provide, say how that capability is turned on for this application, keep tenant and organization boundaries intact, and identify the smallest relevant validation. Do not design a bespoke connector, mapping layer, or import endpoint before establishing whether an installed module already owns this capability.","tags":["architecture","module-facts","reuse-installed","pim-sync"],"owner":{"kind":"facts","path":".ai/guides/modules/sync_akeneo.md","ruleIds":["BC-01","BC-04"]},"expectedRouter":{"required":["architecture"],"allowedExtra":["integration","module-data","framework-context","umes"]},"requiredSkills":["om-integration-builder"],"context":{"required":["AGENTS.md",".ai/guides/architecture.md",".ai/skills/om-integration-builder/SKILL.md",".ai/guides/modules/sync_akeneo.md"],"allowedExtra":[".ai/guides/integrations.md",".ai/guides/contracts.md",".ai/guides/modules/data_sync.md",".ai/skills/om-help/SKILL.md"],"warn":["node_modules/@open-mercato/*/src/**"],"forbidden":[".env*",".git/**"]},"requiredDecisions":["facts-first","app-module-activation","tenant-scope","smallest-validation"],"forbiddenPatterns":["node_modules.{0,40}(?:write|edit|patch)","(?:tenant|organization).{0,30}(?:unscoped|scope optional)"],"validators":["catalog.schema","owner.reference","skills.reference","router.contract","context.budget","context.forbidden","patterns.forbidden"],"maxContextFiles":11,"maxInitialContextBytes":57344,"maxTotalContextBytes":147456,"relatedCases":["OMH-002","OMH-195"]},
-  {"id":"OMH-202","title":"Keep stock counts per warehouse honest and hold goods for confirmed orders without a new module","family":"architecture","mode":"analysis","evaluationKind":"routing","risk":"medium","prompt":"In a freshly scaffolded standalone Open Mercato app, the operations team keeps stock for two storage sites in a spreadsheet: how much of each product sits in which aisle, how much is already promised to confirmed orders, and what has been received, moved, or counted since the last check. They also want a heads-up when an item drops below the level they consider safe. Decide the smallest safe design against what the installed modules already provide, say how that capability is turned on for this application, keep tenant and organization boundaries intact, state the access-control posture for viewing counts versus adjusting them, and identify the smallest relevant validation. Do not model your own stock, location, or reservation tables before establishing whether an installed module already owns this capability.","tags":["architecture","module-facts","reuse-installed","stock-on-hand"],"owner":{"kind":"facts","path":".ai/guides/modules/wms.md","ruleIds":["BC-01","BC-04"]},"expectedRouter":{"required":["architecture"],"allowedExtra":["module-data","backend-ui","umes","framework-context"]},"requiredSkills":["om-help"],"context":{"required":["AGENTS.md",".ai/guides/architecture.md",".ai/skills/om-help/SKILL.md",".ai/guides/modules/wms.md"],"allowedExtra":[".ai/guides/contracts.md",".ai/guides/modules/catalog.md",".ai/guides/modules/sales.md",".ai/skills/om-data-model-design/SKILL.md"],"warn":["node_modules/@open-mercato/*/src/**"],"forbidden":[".env*",".git/**"]},"requiredDecisions":["facts-first","app-module-activation","tenant-scope","acl-features","smallest-validation"],"forbiddenPatterns":["node_modules.{0,40}(?:write|edit|patch)","(?:tenant|organization).{0,30}(?:unscoped|scope optional)"],"validators":["catalog.schema","owner.reference","skills.reference","router.contract","context.budget","context.forbidden","patterns.forbidden"],"maxContextFiles":11,"maxInitialContextBytes":57344,"maxTotalContextBytes":147456,"relatedCases":["OMH-002","OMH-194"]}
+  {"id":"OMH-202","title":"Keep stock counts per warehouse honest and hold goods for confirmed orders without a new module","family":"architecture","mode":"analysis","evaluationKind":"routing","risk":"medium","prompt":"In a freshly scaffolded standalone Open Mercato app, the operations team keeps stock for two storage sites in a spreadsheet: how much of each product sits in which aisle, how much is already promised to confirmed orders, and what has been received, moved, or counted since the last check. They also want a heads-up when an item drops below the level they consider safe. Decide the smallest safe design against what the installed modules already provide, say how that capability is turned on for this application, keep tenant and organization boundaries intact, state the access-control posture for viewing counts versus adjusting them, and identify the smallest relevant validation. Do not model your own stock, location, or reservation tables before establishing whether an installed module already owns this capability.","tags":["architecture","module-facts","reuse-installed","stock-on-hand"],"owner":{"kind":"facts","path":".ai/guides/modules/wms.md","ruleIds":["BC-01","BC-04"]},"expectedRouter":{"required":["architecture"],"allowedExtra":["module-data","backend-ui","umes","framework-context"]},"requiredSkills":["om-help"],"context":{"required":["AGENTS.md",".ai/guides/architecture.md",".ai/skills/om-help/SKILL.md",".ai/guides/modules/wms.md"],"allowedExtra":[".ai/guides/contracts.md",".ai/guides/modules/catalog.md",".ai/guides/modules/sales.md",".ai/skills/om-data-model-design/SKILL.md"],"warn":["node_modules/@open-mercato/*/src/**"],"forbidden":[".env*",".git/**"]},"requiredDecisions":["facts-first","app-module-activation","tenant-scope","acl-features","smallest-validation"],"forbiddenPatterns":["node_modules.{0,40}(?:write|edit|patch)","(?:tenant|organization).{0,30}(?:unscoped|scope optional)"],"validators":["catalog.schema","owner.reference","skills.reference","router.contract","context.budget","context.forbidden","patterns.forbidden"],"maxContextFiles":11,"maxInitialContextBytes":57344,"maxTotalContextBytes":147456,"relatedCases":["OMH-002","OMH-194"]},
+  {
+    "id": "OMH-203",
+    "title": "Evaluate CRM detail-tab UMES routing",
+    "family": "umes",
+    "mode": "analysis",
+    "evaluationKind": "routing",
+    "risk": "medium",
+    "prompt": "How can I add a tab to the customer page?",
+    "tags": [
+      "umes",
+      "backend-ui",
+      "framework-context"
+    ],
+    "owner": {
+      "kind": "skill",
+      "path": ".ai/skills/om-system-extension/SKILL.md",
+      "ruleIds": [
+        "BC-06"
+      ]
+    },
+    "expectedRouter": {
+      "required": [
+        "umes",
+        "backend-ui",
+        "framework-context"
+      ]
+    },
+    "requiredSkills": [
+      "om-system-extension",
+      "om-backend-ui-design",
+      "om-framework-context"
+    ],
+    "context": {
+      "required": [
+        "AGENTS.md",
+        ".ai/guides/extensions.md",
+        ".ai/guides/backend-ui.md",
+        ".ai/guides/modules/customers.md",
+        ".ai/skills/om-system-extension/SKILL.md",
+        ".ai/skills/om-backend-ui-design/SKILL.md",
+        ".ai/skills/om-framework-context/SKILL.md"
+      ],
+      "allowedExtra": [
+        ".ai/skills/om-system-extension/references/extension-branches.md",
+        ".ai/skills/om-system-extension/references/mechanism-selector.md"
+      ],
+      "forbidden": [
+        ".env*",
+        ".git/**",
+        "node_modules/**"
+      ]
+    },
+    "requiredDecisions": [
+      "extension-mechanism",
+      "additive-before-replacement",
+      "extension-entity",
+      "eject-last",
+      "widget-injection-files",
+      "person-detail-tab-spot",
+      "company-detail-tab-spot",
+      "guidance-before-framework-context",
+      "installed-packages-read-only"
+    ],
+    "forbiddenPatterns": [
+      "node_modules.{0,40}(?:write|edit|patch)",
+      "(?:tenant|organization).{0,30}(?:unscoped|scope optional)"
+    ],
+    "validators": [
+      "catalog.schema",
+      "owner.reference",
+      "skills.reference",
+      "router.contract",
+      "context.budget",
+      "context.forbidden",
+      "patterns.forbidden"
+    ],
+    "frameworkContext": [
+      {
+        "module": "customers",
+        "query": "detail:customers."
+      }
+    ],
+    "maxContextFiles": 10,
+    "maxInitialContextBytes": 57344,
+    "maxTotalContextBytes": 131072,
+    "relatedCases": [
+      "OMH-026",
+      "OMH-027"
+    ]
+  }
 ]

package/dist/agentic/shared/ai/harness/cases.schema.json

@@ -3,8 +3,8 @@
   "$id": "https://open-mercato.dev/schemas/standalone-harness-cases.schema.json",
   "title": "Open Mercato standalone harness case catalog",
   "type": "array",
-  "minItems": 202,
-  "maxItems": 202,
+  "minItems": 203,
+  "maxItems": 203,
   "items": {
     "type": "object",
     "additionalProperties": false,
@@ -15,7 +15,7 @@
       "maxTotalContextBytes", "relatedCases"
     ],
     "properties": {
-      "id": { "type": "string", "pattern": "^OMH-(00[1-9]|0[1-9][0-9]|1[0-9][0-9]|20[0-2])$" },
+      "id": { "type": "string", "pattern": "^OMH-(00[1-9]|0[1-9][0-9]|1[0-9][0-9]|20[0-3])$" },
       "title": { "type": "string", "minLength": 12, "maxLength": 180 },
       "family": { "enum": ["architecture", "module", "umes", "integration", "ai-workflow", "bugfix", "business", "testing"] },
       "mode": { "enum": ["analysis", "one-shot", "spec", "bugfix", "review"] },

package/dist/agentic/shared/ai/harness/validators.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "catalog": {
-    "expectedCaseCount": 202,
+    "expectedCaseCount": 203,
     "maxContextFiles": 16,
     "maxInitialContextBytes": 98304,
     "maxTotalContextBytes": 262144,

package/dist/agentic/shared/ai/lessons/_template.md

@@ -0,0 +1,16 @@
+---
+title: "Replace with a concise durable rule"
+modules: ["platform"]
+areas: ["architecture"]
+topics: ["replace-me", "second-topic"]
+---
+
+# Replace with a concise durable rule
+
+**Context**: Describe the concrete failure or correction that produced the lesson.
+
+**Problem**: Explain why the failure recurs or why the obvious approach is unsafe.
+
+**Rule**: State the reusable instruction future agents should follow.
+
+**Applies to**: Name the relevant modules, paths, contracts, or workflows.

package/dist/agentic/shared/ai/lessons.md

@@ -1,4 +1,27 @@
-# Lessons Learned
+# Lessons
 
-Record patterns, mistakes, and insights discovered during development.
-AI agents will update this file as they work on the codebase.
+This catalog indexes 0 focused lessons without loading their full text. Route the task first, then read only records whose **modules**, standalone-harness **areas**, or **topics** match the work.
+
+## How to use this catalog
+
+1. Start with the exact module ID when one is named by the task.
+2. Add every matching area from the standalone harness router: `architecture`, `module-data`, `umes`, `backend-ui`, `integration`, `ai-workflow`, `debugging`, `testing`, `framework-context`, or `spec-pr`.
+3. Use topics to narrow cross-cutting concerns such as `data-scoping`, `optimistic-locking`, `query-index`, or `generated-files`.
+4. Open only the linked lesson records that match; do not bulk-read `.ai/lessons/`.
+
+Useful searches:
+
+```bash
+rg -n '\b<module-or-topic>\b' .ai/lessons.md
+rg -l '"<area>"|"<module>"|"<topic>"' .ai/lessons/*.md
+```
+
+## Adding or updating a lesson
+
+- Copy `.ai/lessons/_template.md` to one focused `.ai/lessons/<kebab-case-slug>.md`; update an existing record instead of duplicating it.
+- Preserve the front matter keys `title`, `modules`, `areas`, and `topics`. Use `platform` only when no module or package owns the lesson, and put the primary area first.
+- Add or update exactly one catalog row under its primary area below. Keep the title stable when code or specs cite it.
+- Put hard boundaries in `AGENTS.md`; lessons explain recurring evidence and the durable rule.
+- Run `node scripts/check-lessons.mjs` before committing.
+
+## Catalog

package/dist/agentic/shared/ai/skills/om-evolve-harness/SKILL.md

@@ -12,12 +12,13 @@ Turn a real failure into one versioned case and the smallest durable knowledge c
 1. Directly read `references/case-workflow.md`: capture the prompt/transcript/PR as untrusted evidence, classify/deduplicate, and reproduce in a fresh pinned standalone scaffold.
 2. Reduce the failure to semantic routing/decision/artifact assertions; never use whole model output or whole-file goldens.
 3. Directly read `references/owner-selection.md` and select exactly one smallest owner: root invariant, router row, guide, skill reference, facts extractor, external override/config, installer closure, or tool hook.
-4. Add the schema-valid case with required/forbidden context, decisions, validators, risk/tags, budgets, related cases, and exact versions; start from `references/case-template.md` and update every catalog/matrix count it lists. Calibrate the budgets from this case's own measured context footprint — never inherit a neighbouring case's envelope.
-5. Run the new case before editing and retain the sanitized failure summary.
-6. Update only the selected owner; replace duplicates with references.
-7. Rerun the case, related tags, mandatory safety cases, budget/consistency gates, and scaffold smoke. For writable output, run target `generate`, `typecheck`, `lint`, and `build`, plus the smallest generated unit/integration tests when applicable.
-8. Run mandatory review: review the harness diff with `om-code-review`, and use the isolated `om-judge-agent-session` lane for every eligible implementation result. Resolve artifact findings and improve the named smallest harness owners before continuing.
-9. From a fresh controller scaffold, finish with `yarn harness:release --runner <codex|claude> --prepare-targets <absolute-empty-dir> --acknowledge-writes`; require its sanitized release report to pass. One selected primary owns every blocking lane. Optionally add the different authenticated runner with `--portability-runner <runner>` for the representative read-only portability lane. Report before/after evidence and exact tool/model versions.
+4. Scan `.ai/lessons.md` by the case's selected areas, modules, and important topics. Open only matching records; when the evidence produces a reusable app-level correction, update one focused lesson record and its index row instead of growing the index or duplicating knowledge owners.
+5. Add the schema-valid case with required/forbidden context, decisions, validators, risk/tags, budgets, related cases, and exact versions; start from `references/case-template.md` and update every catalog/matrix count it lists. Calibrate the budgets from this case's own measured context footprint — never inherit a neighbouring case's envelope.
+6. Run the new case before editing and retain the sanitized failure summary.
+7. Update only the selected owner; replace duplicates with references.
+8. Rerun the case, related tags, mandatory safety cases, budget/consistency gates, and scaffold smoke. For writable output, run target `generate`, `typecheck`, `lint`, and `build`, plus the smallest generated unit/integration tests when applicable.
+9. Run mandatory review: review the harness diff with `om-code-review`, and use the isolated `om-judge-agent-session` lane for every eligible implementation result. Resolve artifact findings and improve the named smallest harness owners before continuing.
+10. From a fresh controller scaffold, finish with `yarn harness:release --runner <codex|claude> --prepare-targets <absolute-empty-dir> --acknowledge-writes`; require its sanitized release report to pass. One selected primary owns every blocking lane. Optionally add the different authenticated runner with `--portability-runner <runner>` for the representative read-only portability lane. Report before/after evidence and exact tool/model versions.
 
 ## Rules
 

package/dist/agentic/shared/ai/skills/om-system-extension/SKILL.md

@@ -13,7 +13,7 @@ Route before reading: choose routes from the request and mechanism selector, the
 
 1. Read `.ai/guides/extensions.md` and `references/mechanism-selector.md`; choose UMES, supported override, package, or eject.
 2. Resolve host entity/route/spot/component/event IDs from generated facts. Invoke `om-framework-context` only when facts omit the needed contract.
-3. Follow the selected branch in `references/extension-branches.md` for enricher, API/command interceptor, guard, widget/menu, extension entity, subscriber, or component replacement. For `entry.overrides`, load `references/unified-overrides.md` and select the exact domain/key.
+3. Follow the matching `references/extension-branches.md` branch. UI widgets live in `src/modules/<id>/widgets/injection/**` and register an exact facts- or context-resolved spot in `src/modules/<id>/widgets/injection-table.ts`. For `entry.overrides`, load `references/unified-overrides.md` and select the exact domain/key.
 4. Invoke `om-data-model-design` only when the extension adds app-owned persistence; an enricher/interceptor/widget-only round trip does not need it.
 5. For editable additions, follow `references/read-write-roundtrip.md`; implement input, authenticated write, stored data, list/detail read, UI hydration, clear-to-null, and conflict behavior. An editable addition that must survive reload is necessarily a persisted field: select `module-data`, read contracts, and invoke `om-data-model-design`.
 6. Run `yarn generate`; verify host-present/absent, authorized/denied/wildcard, cache/search, and failure fallback using `references/verification.md`.

package/dist/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md

@@ -1,6 +1,6 @@
 # Unified Override Domains
 
-Load this reference when `src/modules.ts` must disable or replace an installed contribution. `entry.overrides` is the only canonical app-level override umbrella. Resolve every domain/key from the named module sheet's `UMES contributions` override facts first, following `fact-ref` provenance to the existing route/page/event/worker/widget/agent/tool/setup/ACL/DI/encryption facts. Use exact installed context only for one named missing fact. For keyed override maps, `null` disables a supported contribution and a typed value replaces it; AI extensions and setup hooks have the special shapes below.
+Load this reference when `src/modules.ts` must disable or replace an installed contribution. `entry.overrides` is the only canonical app-level override umbrella. Resolve the exact key from the named module sheet's generated `overrideTargets` facts first: each target carries the exact top-level `domain`, the complete `path` segments, the terminal `key` for keyed-record domains, the supported `modes`, a `factRef` to the module-owned fact being overridden, and a portable `source`. Follow `factRef` provenance to the underlying route/page/event/worker/widget/agent/tool/setup/ACL/DI/encryption fact. When the module sheet reports an `overrideTargetDiagnostics` entry (`missing-owned-fact`, `missing-source`, `unsupported-dynamic-key`, `unknown-framework-domain`) for the domain you need, treat it as a blocker and escalate to the named source for one missing detail — never guess a key. Framework-only settings such as `nav.groupOrder` live in `framework-extension-points.md`, not in a module's `overrideTargets`. For keyed override maps, `null` disables a supported contribution and a typed value replaces it; AI extensions and setup hooks have the special shapes below.
 
 | Domain | Shape/key |
 |---|---|
@@ -30,7 +30,9 @@ Load this reference when `src/modules.ts` must disable or replace an installed c
 - API route methods are case-insensitive and paths normalize a leading/trailing slash; use the canonical displayed key. Disabling all methods removes the route entry.
 - Page keys name generated frontend/backend URL paths, not filesystem paths. After hiding a landing page, provide a safe accessible redirect.
 - Injection/dashboard keys are generated entry keys and may differ from widget metadata IDs. Worker keys are resolved descriptor IDs; inspect generated facts/source instead of constructing them from memory.
-- Require the generated override fact's exact `domain`, `key`, and mode (`disable-replace`, `replace`, or `additive`). A stale or `unresolved` first-party correlation is a blocker; it is not a fallback to a guessed key.
+- Require the generated `overrideTargets` entry's exact `domain`, `path`/`key`, and `modes` (`disable-replace`, `replace`, or `additive`). A stale or `unresolved` first-party correlation, or an `overrideTargetDiagnostics` row for that domain, is a blocker; it is not a fallback to a guessed key. Copy the `path` verbatim — do not flatten nested widget/AI segments.
+- `overrides.guards` targets backend/frontend page route middleware only (the `page-middleware` owned fact). A `data/guards.ts` mutation guard is a different contract with no override domain; it surfaces as an extension activation, never under `overrides.guards`. The target's `page-middleware-not-mutation-guard` note flags this.
+- Before adding a contribution, check the target module sheet's `incoming` index for an already-installed contributor of the same kind/target, and require a `bound` `activation` (not a broad capability host) before assuming a route/entity extension actually runs. A `capability-only` host is available but unproven; do not claim runtime invocation from it.
 - Keep AI extensions additive and ordered. Use agent/tool maps only for replacement or disable; do not encode an extension as a `null`-capable map entry.
 - Preserve replacement type/signature, auth/features, scope, stable ID, and observable side effects. A replacement may strengthen safety but never silently narrow a public contract.
 - Treat unknown/stale override diagnostics as failures. Run `yarn generate`, clear structural nav/module caches with the app's documented command, and verify the old contribution is absent in every bootstrap.

package/dist/agentic/shared/scripts/check-lessons.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+export const LESSON_AREAS = new Set([
+  'architecture',
+  'module-data',
+  'umes',
+  'backend-ui',
+  'integration',
+  'ai-workflow',
+  'debugging',
+  'testing',
+  'framework-context',
+  'spec-pr',
+])
+
+const INDEX_MAX_BYTES = 30 * 1024
+const RECORD_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
+const MODULE_PATTERN = /^[a-z0-9]+(?:_[a-z0-9]+)*$/
+const TOPIC_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const INDEX_ROW_PATTERN = /^- \[(.+)]\(lessons\/([a-z0-9-]+\.md)\) — area:([^;]+); module:([^;]+); topic:(.+)$/
+
+function parseFrontMatter(source, relativePath, errors) {
+  const match = source.match(/^---\n([\s\S]*?)\n---\n\n# (.+)\n/)
+  if (!match) {
+    errors.push(`${relativePath}: expected JSON-valued front matter followed by one H1`)
+    return null
+  }
+
+  const metadata = {}
+  for (const line of match[1].split('\n')) {
+    const separator = line.indexOf(':')
+    if (separator < 1) {
+      errors.push(`${relativePath}: malformed front matter line ${JSON.stringify(line)}`)
+      continue
+    }
+    const key = line.slice(0, separator)
+    try {
+      metadata[key] = JSON.parse(line.slice(separator + 1).trim())
+    } catch {
+      errors.push(`${relativePath}: ${key} must use valid JSON syntax`)
+    }
+  }
+
+  const expectedKeys = ['title', 'modules', 'areas', 'topics']
+  const actualKeys = Object.keys(metadata).sort()
+  if (JSON.stringify(actualKeys) !== JSON.stringify([...expectedKeys].sort())) {
+    errors.push(`${relativePath}: front matter keys must be exactly ${expectedKeys.join(', ')}`)
+  }
+  if (typeof metadata.title !== 'string' || metadata.title.length === 0) {
+    errors.push(`${relativePath}: title must be a non-empty string`)
+  } else if (metadata.title !== match[2]) {
+    errors.push(`${relativePath}: front matter title must match the H1`)
+  }
+
+  for (const key of ['modules', 'areas', 'topics']) {
+    if (!Array.isArray(metadata[key])) errors.push(`${relativePath}: ${key} must be an array`)
+  }
+  if (!Array.isArray(metadata.modules) || metadata.modules.length === 0) {
+    errors.push(`${relativePath}: modules must contain an owning module/package or platform`)
+  } else if (metadata.modules.some((value) => typeof value !== 'string' || !MODULE_PATTERN.test(value))) {
+    errors.push(`${relativePath}: modules must use lowercase snake_case tags`)
+  }
+  if (!Array.isArray(metadata.areas) || metadata.areas.length === 0) {
+    errors.push(`${relativePath}: areas must contain at least one standalone router area`)
+  } else if (metadata.areas.some((value) => !LESSON_AREAS.has(value))) {
+    errors.push(`${relativePath}: areas contain a value outside the standalone router taxonomy`)
+  }
+  if (!Array.isArray(metadata.topics) || metadata.topics.length < 2 || metadata.topics.length > 6) {
+    errors.push(`${relativePath}: topics must contain between two and six important concepts`)
+  } else if (metadata.topics.some((value) => typeof value !== 'string' || !TOPIC_PATTERN.test(value))) {
+    errors.push(`${relativePath}: topics must use lowercase kebab-case tags`)
+  }
+
+  for (const key of ['modules', 'areas', 'topics']) {
+    if (Array.isArray(metadata[key]) && new Set(metadata[key]).size !== metadata[key].length) {
+      errors.push(`${relativePath}: ${key} must not contain duplicates`)
+    }
+  }
+
+  return metadata
+}
+
+export function checkLessonsCatalog(rootDir) {
+  const errors = []
+  const indexPath = path.join(rootDir, '.ai', 'lessons.md')
+  const lessonsDir = path.join(rootDir, '.ai', 'lessons')
+  if (!fs.existsSync(indexPath)) return [`${indexPath}: lesson index is missing`]
+
+  const indexSource = fs.readFileSync(indexPath, 'utf8')
+  const indexBytes = Buffer.byteLength(indexSource)
+  if (indexBytes > INDEX_MAX_BYTES) {
+    errors.push(`.ai/lessons.md: ${indexBytes} bytes exceeds the ${INDEX_MAX_BYTES}-byte progressive-loading budget`)
+  }
+  if (/\*\*(?:Context|Problem|Rule|Applies to)\*\*:/.test(indexSource)) {
+    errors.push('.ai/lessons.md: full lesson prose belongs in .ai/lessons/, not the catalog')
+  }
+
+  const recordNames = fs.existsSync(lessonsDir)
+    ? fs.readdirSync(lessonsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('_'))
+      .map((entry) => entry.name)
+      .sort()
+    : []
+  const records = new Map()
+  const titles = new Set()
+  for (const fileName of recordNames) {
+    const relativePath = `.ai/lessons/${fileName}`
+    if (!RECORD_NAME_PATTERN.test(fileName)) errors.push(`${relativePath}: filename must use kebab-case`)
+    const metadata = parseFrontMatter(fs.readFileSync(path.join(lessonsDir, fileName), 'utf8'), relativePath, errors)
+    if (!metadata) continue
+    if (titles.has(metadata.title)) errors.push(`${relativePath}: duplicate lesson title ${JSON.stringify(metadata.title)}`)
+    titles.add(metadata.title)
+    records.set(fileName, metadata)
+  }
+
+  const indexed = new Set()
+  for (const line of indexSource.split('\n')) {
+    if (!line.startsWith('- [')) continue
+    const match = line.match(INDEX_ROW_PATTERN)
+    if (!match) {
+      errors.push(`.ai/lessons.md: malformed catalog row ${JSON.stringify(line)}`)
+      continue
+    }
+    const [, title, fileName, areaText, moduleText, topicText] = match
+    if (indexed.has(fileName)) errors.push(`.ai/lessons.md: duplicate link to lessons/${fileName}`)
+    indexed.add(fileName)
+    const metadata = records.get(fileName)
+    if (!metadata) {
+      errors.push(`.ai/lessons.md: lessons/${fileName} does not exist`)
+      continue
+    }
+    const indexedMetadata = {
+      title,
+      areas: areaText.split(','),
+      modules: moduleText.split(','),
+      topics: topicText.split(','),
+    }
+    for (const key of ['title', 'areas', 'modules', 'topics']) {
+      if (JSON.stringify(indexedMetadata[key]) !== JSON.stringify(metadata[key])) {
+        errors.push(`.ai/lessons.md: ${key} drift for lessons/${fileName}`)
+      }
+    }
+  }
+
+  for (const fileName of records.keys()) {
+    if (!indexed.has(fileName)) errors.push(`.ai/lessons/${fileName}: record is missing from the catalog`)
+  }
+  const declaredCount = indexSource.match(/catalog indexes (\d+) focused lessons/)
+  if (!declaredCount || Number(declaredCount[1]) !== records.size) {
+    errors.push(`.ai/lessons.md: declared lesson count must equal ${records.size}`)
+  }
+
+  return errors
+}
+
+function parseRoot(args) {
+  if (args.length === 0) return process.cwd()
+  if (args.length === 2 && args[0] === '--root') return path.resolve(args[1])
+  throw new Error('Usage: check-lessons.mjs [--root <app-root>]')
+}
+
+export function main(args = process.argv.slice(2)) {
+  const rootDir = parseRoot(args)
+  const errors = checkLessonsCatalog(rootDir)
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`- ${error}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`Lessons catalog is valid: ${rootDir}`)
+}
+
+const entryPath = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null
+if (entryPath === import.meta.url) main()