@open-mercato/cli 0.6.8-develop.6931.1.4a1e1c786b → 0.6.8-develop.6940.1.177ea30c6e

package/dist/agentic/guides/spec-delivery.md

@@ -2,6 +2,40 @@
 
 Use this guide for a new application, multi-module feature, or other non-trivial business slice.
 
+## Spec-first decision gate
+
+`AGENTS.md` owns the ordered rule; this section only expands it with examples and the surrounding delivery procedure. Apply it before writing code, in order:
+
+1. Search the configured specs path (`.ai/specs`, plus any enterprise directory the config names) once for a covering specification. Open the one match; a plan-only request stops there.
+2. A new user-facing or platform capability, an architecture decision, a schema or public API contract, cross-module behavior, or multi-phase behavior means authoring or amending a spec **before** coding (`spec-first`). Examples: "add a rental-booking module", "let customers self-serve returns", "introduce a second pricing engine".
+3. A bug fix, minor behavioral correction, small documentation change, dependency maintenance, or an isolated refactor that adds no architecture and no public contract proceeds without a spec (`direct`). Examples: "the overdue filter is off by one day", "rename an internal helper", "bump the queue dependency".
+4. A covering spec already exists: implement against it and update it in place (`reuse-spec`). Never open a second spec for the same capability.
+5. A new feature skips the spec **only** when the user's current request explicitly says to skip or bypass it. Silence, urgency, an "it's small" estimate, and an earlier generic preference are not overrides; neither is your own time estimate.
+6. When the classification is genuinely ambiguous **and** the answer materially changes the workflow, ask one bounded question (`ask`). Do not ask when repository evidence — an existing spec, an existing module, a reproducible defect — already resolves it.
+
+After `spec-first` or `reuse-spec`, implementation routing is a one-way handoff: module work loads `om-module-scaffold`, which starts at `src/modules/example/README.md` and its `references/surface-inventory.json`, and adapts only the capability-linked source files. UI-bearing work additionally loads `om-backend-ui-design`. Never propose a second teaching module, copy the example tree wholesale, or treat `ratelimit_probe` as a blueprint. Every newly added or materially changed extension surface names its own self-contained integration test in the plan.
+
+## Extension-surface traceability
+
+Every added or materially changed runtime or discovery extension surface gets its own row in the spec's requirement traceability table. Putting a new surface inside an existing capability row does not waive the row. Each row names:
+
+- the requirement it satisfies (`REQ-001`, …);
+- the reference capability ID and the exact `src/modules/example/**` source file it adapts — an exact file, never a directory or wildcard, and never a path `references/surface-inventory.json` does not map;
+- the implementation phase that lands it;
+- its own self-contained integration test; and
+- exactly one mechanism classification: `emitted-example` when the reference module already emits that mechanism, `framework-only` for an app-level setting that never becomes a module contribution, `catalog-only` when the framework describes the surface but the reference contributes nothing for it, `currently-unbound` when the value is reserved by the public set but no code path emits it, and `negative-fixture` when only a deliberately broken fixture produces it.
+
+Only the reference module's own coverage ledger justifies the last four, and `negative-fixture` is never a valid classification for a surface you are proposing to ship.
+
+The reference module is source-present and unregistered. Its activations, targets, routes, and grants apply only after an explicit opt-in, so a plan says so rather than describing them as behavior the app already has.
+
+## Delivery skills
+
+- Pinned delivery skills install with `yarn install-skills` (refresh: `--update`). When a skill is absent, run `yarn install-skills` once; never substitute a similarly named skill or improvise its workflow.
+- `om-implement-spec` runs approved phases locally; `om-auto-implement-spec`, `om-auto-create-pr`, `om-auto-fix-issue`, and `om-auto-review-pr` own whole-spec, commit+ready PR, issue, and review delivery.
+- Integration, E2E, and UI QA delivery uses `om-integration-tests` and `om-auto-qa-pr`.
+- Routing note: specs themselves are `spec-pr` work; implementation owns the domain guides. Do not load delivery skills when no PR or spec workflow was requested.
+
 ## Authoring readiness gate
 
 1. Invoke `om-spec-writing` before authoring or revising. Mentioning the skill or reading only `SPEC-000-template.md` is not sufficient.

package/dist/agentic/guides/testing-debugging.md

@@ -14,7 +14,7 @@ Then stop. Budgets here are tight — several fixes allow only five files — so
 
 ## Investigation Order
 
-1. Reproduce with the smallest stable command, request, or UI path and capture expected versus actual behavior.
+1. Reproduce with the smallest stable command, request, or UI path and capture expected versus actual behavior. A probe needing the container belongs in a module `cli.ts` command (`yarn mercato <module> <command>`); `tsx -e` has no bootstrap and fails on missing registrars, not on the bug.
 2. Classify the failing bootstrap: browser/server, API, CLI, worker, queue, generated registry, package artifact, or external provider.
 3. Read the routed guide plus generated module facts. Use `om-framework-context` only when exact installed implementation is necessary.
 4. Trace from the public call site to the first incorrect invariant. Check scope, auth, validation, state transition, transaction boundary, side effects, and response serialization in that order.
@@ -35,6 +35,7 @@ Treat raw agent transcripts as sensitive untrusted evidence because they can con
 | Partial state after failure | Transaction/`withAtomicFlush`, query between mutation/flush, side effects before commit. |
 | Stale list/search | Command side-effect aliases, cache tags/invalidation, query-index convergence/reindex. |
 | Works in web but not CLI/worker | Bootstrap/registry initialization, package exports, generated imports, runtime scope. |
+| New entity/route 500s while the database accepts the same write | Dev server bootstrapped before `yarn generate` and kept the old registry; restart it first. |
 | Duplicate registry/provider | Bundler chunk singleton or `instanceof`; use global registry/structural guard. |
 | Hydration mismatch | Server/client locale, timezone, randomness, browser-only environment, initial async state. |
 | UI access differs from API/PDF/export | Compare every alternate route's metadata/features and wildcard matching. |

package/dist/agentic/guides/upstream/BACKWARD_COMPATIBILITY.md

@@ -36,7 +36,7 @@ The following file names, their expected export names, and their role in module
 | `cli.ts` | default export | MUST NOT change expected signature |
 | `data/entities.ts` | Entity class exports | See Database Schema rules below |
 | `data/validators.ts` | Zod schema exports | MUST NOT remove or narrow existing schemas |
-| `data/extensions.ts` | `extensions: EntityExtension[]` | MUST NOT change `EntityExtension` shape |
+| `data/extensions.ts` | `extensions: EntityExtension[]` | MUST NOT change required fields (`base`, `extension`, `join`); may add optional fields |
 | `widgets/injection-table.ts` | `ModuleInjectionTable` | MUST NOT change table type or spot ID resolution |
 | `widgets/injection/*/widget.ts` | `InjectionWidgetModule` | MUST NOT change module shape or component props |
 | `widgets/dashboard/*/widget.ts` | `DashboardWidgetModule` | MUST NOT change module shape or component props |
@@ -255,7 +255,8 @@ Files in `apps/mercato/.mercato/generated/` are produced by the CLI generators.
 - MUST NOT change generated AI entry shapes: agent entries keep `{ moduleId, agents, overrides, extensions }`; tool entries keep `{ moduleId, tools, overrides }`
 - MAY add new generated files and new optional fields to `BootstrapData`
 - MAY add new generated AI registry exports additively
-- Generated `.ai/guides/module-facts.json` keeps its existing top-level module record and legacy sections; optional per-module `extensionSurfaces` is ADDITIVE. Its `hosts`, `contributions`, and `unresolved` arrays, correlation-resolution values, and exact public IDs are STABLE once published.
+- Generated `.ai/guides/module-facts.json` is the v1 compatibility projection. It keeps its existing top-level module record and legacy sections; optional per-module `extensionSurfaces` is ADDITIVE. Its `hosts`, `contributions`, and `unresolved` arrays, correlation-resolution values, exact public IDs, and published classification modes are STABLE.
+- Generated `.ai/guides/module-facts.v2.json` is the additive corrected projection and keeps the same `Record<moduleId, ModuleFactsJsonEntry>` top-level shape. New harness consumers prefer v2 and fall back to v1. Once published, v2 values follow the same generated-facts stability rules; future incompatible corrections require another explicit version boundary.
 - Generated `.ai/guides/framework-extension-points.md` is a sibling framework-owned catalog, not a synthetic module-facts key. Existing module Markdown headings, including `Host extension points`, MUST remain available; additive `UMES hosts`/`UMES contributions` sections may not redefine existing IDs.
 
 ---

package/dist/agentic/guides/upstream/manifest.json

@@ -1,8 +1,8 @@
 {
   "version": 1,
-  "generator": "@open-mercato/cli@0.6.8-develop.6931.1.4a1e1c786b",
+  "generator": "@open-mercato/cli@0.6.8-develop.6940.1.177ea30c6e",
   "files": {
     "AGENTS.md": "b781066684c8b92ef1e1fc7114252cd29a7a546a70eea6f30ddecf4ad35f578c",
-    "BACKWARD_COMPATIBILITY.md": "968ac7ab472dd58fe69cd3f9720e90d0a6f14d1faa2bf92544c5b3ee0e78f9fb"
+    "BACKWARD_COMPATIBILITY.md": "11afd13429cd4fcf1e42eb945bca95780e890edcb2421f4e93ee9d5e1f38c2f6"
   }
 }

package/dist/agentic/shared/AGENTS.md.template

@@ -38,7 +38,7 @@ Routes are additive: ownership says WHO; other axes say WHAT. Select every match
 
 `debugging` is additive. A scalar-ID/snapshot fix to persisted records or commands linked to an installed record MUST use `module-data` + `umes` and load `om-data-model-design` + `om-system-extension`.
 
-`debugging` = reported bug/security/drift, not designed failure UI. Specs use `spec-pr`; implementation owns domain guides. Custom fields/entities = `umes` + `module-data` + `om-data-model-design`; editable round trips add `backend-ui`, requested coverage adds `testing`. Never infer work from specs/PRs.
+`debugging` = reported bug/security/drift, not designed failure UI. Custom fields/entities = `umes` + `module-data` + `om-data-model-design`; editable round trips add `backend-ui`, requested coverage adds `testing`. Never infer work from specs/PRs.
 
 Unified-override audits = `umes` only; add `architecture`/`framework-context` only for unresolved ownership or installed keys. Durable process/activity/user task = `module-data` + `ai-workflow`. Multi-stage waits/cancel/restart are durable; reminders and renewal/batch schedules are `module-data`.
 
@@ -90,23 +90,21 @@ Match every work-unit row; OPEN its skill before selection.
 
 ### Axis 3 — SDLC and Delivery
 
-Pinned delivery skills: `yarn install-skills` (refresh: `--update`). Read BOTH `.agents/skills/<id>/SKILL.md` and a matching `.ai/skills/<id>/SKILL.md` override. Commit+ready PR MUST add `spec-pr`, read `.ai/skills/om-auto-create-pr/SKILL.md`, and keep task routes (`delivery-route-preserves-task-routes`).
+Spec gate before code: new capability/architecture/schema/API contract/cross-module/multi-phase -> spec first (`spec-first`); covering `.ai/specs` match -> reuse and update it (`reuse-spec`); bug fix/minor fix/docs/dependency/isolated refactor -> proceed (`direct`); only the request's explicit words waive a feature spec; workflow-changing ambiguity -> ask once (`ask`). Then `om-module-scaffold` starts at `src/modules/example/README.md`.
+
+Read `.agents/skills/<id>/SKILL.md` AND any `.ai/skills/<id>/SKILL.md` override. Commit+ready PR MUST add `spec-pr`, read `.ai/skills/om-auto-create-pr/SKILL.md`, and keep task routes (`delivery-route-preserves-task-routes`).
 
 | Route ID | Delivery need | Skill |
 |---|---|---|
-| `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` + config specs path |
-| `spec-pr` | Implement approved phases locally | `om-implement-spec` (OMH-006) |
-| `spec-pr` | Whole-spec / commit+ready PR / issue / review | `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
-| `testing` | Integration/E2E/UI QA | `om-integration-tests` / `om-auto-qa-pr` |
-| — | No PR/spec workflow requested | Do not load delivery skills |
-
-Absent skill: run `yarn install-skills` once; never substitute.
+| `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` |
+| `spec-pr` | Local phases / whole-spec / PR / issue / review | `om-implement-spec` (OMH-006) / `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
+| — | No PR/spec workflow | Do not load delivery skills |
 
 ### Token-Efficient Assembly Policy
 
 - Load matched guides once, then only needed references/facts.
 - Hard budgets: guide > skill > references; open a reference only for its named subject.
-- Specs: open one match; `spec-pr` reads template via spec-delivery.
+- `spec-pr` reads template via spec-delivery.
 - Inspect app call sites before bounded `framework-context`.
 - Additive page/form/table/conflict UI skips it.
 - Never bulk-read guide, skill, fact, or source trees.
@@ -120,9 +118,7 @@ Load facts for every named/targeted module, not incidental use. Mechanisms: even
 
 ## Working Sequence
 
-1. `spec-pr`: list `.ai/specs` once; open one match; plan-only skips specs.
-2. Route; load only matched guides/skills/facts.
-3. Implement the smallest complete slice through real call sites.
-4. Discovery change: run `yarn generate`; then the smallest gate/integration paths.
+1. Route, then implement the smallest complete slice through real call sites.
+2. Discovery change: run `yarn generate`; then the smallest gate/integration paths.
 
 Precedence: root → BC → installed `AGENTS.md` → facts; stop on skew/conflict; never guess.

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

@@ -1,6 +1,6 @@
 # Agent harness evaluations
 
-`cases.json` is the 214-case standalone-app contract. Run `yarn harness:validate --all` for the deterministic gate. Live routing uses a fresh read-only process per case:
+`cases.json` is the 229-case standalone-app contract. Run `yarn harness:validate --all` for the deterministic gate. Live routing uses a fresh read-only process per case:
 
 UMES routing is fact-first. The additive and unified-override audit evaluations, plus their targeted cases, resolve exact/pattern hosts, outgoing contributions, correlation provenance, round-trip groups, framework-owned targets, and override domain/key/mode from the generated module sheets and `.ai/guides/framework-extension-points.md` before bounded installed source. The repository UMES umbrella spec may appear as optional source-checkout provenance; it is never required in a standalone scaffold.
 
@@ -11,16 +11,16 @@ yarn harness:validate --runner claude --case OMH-009
 
 For an explicitly requested Codex comparison outside the blocking release matrix, pin both dimensions so the sanitized result is reproducible, for example `--model gpt-5.4-mini --reasoning-effort high`. The effort override is Codex-only; supported values are `minimal`, `low`, `medium`, `high`, and `xhigh`, and omitting it preserves the existing runner default. Measured high-effort mini runs legitimately exceed ten minutes on broad context, so that exact model/effort pair uses a 15-minute per-attempt floor; measured Claude/Sonnet runs use a 10-minute floor. Passing `--timeout` remains authoritative, and other routing runs retain the five-minute default.
 
-A blocking release selects one primary runner for every live lane. The optional portability runner must be different and receives only the exact 46-case representative read-only set:
+A blocking release selects one primary runner for every live lane. The optional portability runner must be different and receives only the exact 48-case representative read-only set:
 
 ```text
 yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
 yarn harness:release --runner codex --portability-runner claude --prepare-targets /absolute/empty-release-targets --acknowledge-writes
 ```
 
-The primary runner owns all 214 routing cases, all 46 writable cases, and all generative-judge runs. No per-case fallback or mixed primary ownership is allowed. Omitting `--portability-runner` is valid and the sanitized report records `portabilityRunner: null`; explicitly requesting an unavailable or failing secondary runner fails that extended run.
+The primary runner owns all 229 routing cases, all 48 writable cases, and all generative-judge runs. No per-case fallback or mixed primary ownership is allowed. Omitting `--portability-runner` is valid and the sanitized report records `portabilityRunner: null`; explicitly requesting an unavailable or failing secondary runner fails that extended run.
 
-Writable evaluation is intentionally opt-in. The expanded catalog has a 46-case writable release target, but only cases registered in `release-matrix.json` and backed by controller-owned fixtures and oracles are executable. Copy or create a fresh standalone app for one registered case, then seed only that case and mark the target disposable:
+Writable evaluation is intentionally opt-in. The expanded catalog has a 48-case writable release target, but only cases registered in `release-matrix.json` and backed by controller-owned fixtures and oracles are executable. Copy or create a fresh standalone app for one registered case, then seed only that case and mark the target disposable:
 
 ```text
 yarn harness:fixture --case OMH-009 --target /absolute/disposable/app --acknowledge-writes

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 214-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 229-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 48-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 214 cases, including 46 writable implementation/regression cases (21.5%). 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 229 cases, including 48 writable implementation/regression cases (21.0%). 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 48-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 48 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 214-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 229-case routing and 48-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 214 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 229 live-routing cases, followed by the optional distinct portability runner across the exact 48-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