@nextcommerce/campaigns-os 1.34.1 → 1.37.2

package/schemas/campaigns-os-progress-snapshot.v0.schema.json

@@ -0,0 +1,370 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-progress-snapshot.v0.schema.json",
+  "title": "Campaigns OS minimal progress observation v0",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "snapshot_id",
+    "stream_id",
+    "sequence",
+    "previous_snapshot_id",
+    "observed_at",
+    "package_version",
+    "producer",
+    "identity",
+    "stages",
+    "preview",
+    "continuation",
+    "qa"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-progress-snapshot/v0"
+    },
+    "snapshot_id": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "stream_id": {
+      "type": "string",
+      "pattern": "^progress_[0-9a-f]{32}$"
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "previous_snapshot_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "observed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "package_version": {
+      "type": "string",
+      "pattern": "^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$"
+    },
+    "producer": {
+      "enum": [
+        "next",
+        "qa"
+      ]
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "map_id",
+        "map_revision_hash",
+        "map_revision_algorithm",
+        "saved_revision_alignment",
+        "local_spec_material_hash",
+        "local_spec_material_algorithm",
+        "build_fingerprint",
+        "build_fingerprint_algorithm"
+      ],
+      "properties": {
+        "map_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Za-z0-9_-]{1,64}$"
+        },
+        "map_revision_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "map_revision_algorithm": {
+          "const": "map-store-v1"
+        },
+        "saved_revision_alignment": {
+          "enum": [
+            "aligned",
+            "unconfirmed"
+          ]
+        },
+        "local_spec_material_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "local_spec_material_algorithm": {
+          "const": "campaign-spec-material-v1"
+        },
+        "build_fingerprint": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "build_fingerprint_algorithm": {
+          "const": "sha256-manifest/v1"
+        }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 6,
+      "maxItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "stage",
+          "status",
+          "build_binding",
+          "source_build_fingerprint"
+        ],
+        "properties": {
+          "stage": {
+            "enum": [
+              "prepare_build",
+              "setup",
+              "assembly",
+              "polish",
+              "deploy",
+              "qa"
+            ]
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "required",
+              "blocked",
+              "completed",
+              "completed_with_warnings",
+              "skipped",
+              "unknown"
+            ]
+          },
+          "build_binding": {
+            "enum": [
+              "matching",
+              "unconfirmed"
+            ]
+          },
+          "source_build_fingerprint": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          }
+        }
+      }
+    },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "present",
+        "url_hash"
+      ],
+      "properties": {
+        "present": {
+          "type": "boolean"
+        },
+        "url_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    },
+    "continuation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "stage",
+        "blocked",
+        "divergent",
+        "action_ids",
+        "gates"
+      ],
+      "properties": {
+        "stage": {
+          "enum": [
+            "prepare-build",
+            "doctor-blocked",
+            "setup",
+            "build",
+            "polish",
+            "deploy",
+            "qa",
+            "done",
+            "unknown"
+          ]
+        },
+        "blocked": {
+          "type": "boolean"
+        },
+        "divergent": {
+          "type": "boolean"
+        },
+        "action_ids": {
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "doctor_recheck",
+              "restore_prepare_build_binding",
+              "recheck",
+              "rerun_prepare_build",
+              "divergence_inspect",
+              "setup_skill",
+              "build_skill",
+              "build_local_proof",
+              "build_production_parity",
+              "polish_skill",
+              "deploy",
+              "advance",
+              "install_browser",
+              "qa_run",
+              "run_end",
+              "run_record_present",
+              "run_record_remit_recovery",
+              "run_record_closeout",
+              "purchase_proof_unknown",
+              "theme_gate.starter_palette_blocks_qa",
+              "theme_gate.brand_contract_unreadable",
+              "theme_gate.theme_generate",
+              "theme_gate.apply_brand_layer",
+              "theme_gate.waive_theme",
+              "theme_gate.fix_load_order",
+              "polish_gate.rerun_build",
+              "polish_gate.run_polish",
+              "polish_gate.repair_waiver",
+              "checkpoint.page_kit.sdk_version.repair_spec",
+              "checkpoint.page_kit.sdk_version.refresh_spec",
+              "checkpoint.page_kit.store_profile.repair_spec",
+              "checkpoint.built_output.upsell_selector_scope.repair_selectors",
+              "checkpoint.page_kit.sdk_version.repair_target",
+              "checkpoint.page_kit.sdk_version.align_store_profile",
+              "checkpoint.page_kit.sdk_version.align_sdk_version",
+              "checkpoint.page_kit.sdk_version.repair_waiver",
+              "checkpoint.page_kit.sdk_version.waive",
+              "checkpoint.page_kit.store_profile.repair_target",
+              "checkpoint.page_kit.store_profile.align_store_profile",
+              "checkpoint.page_kit.store_profile.align_sdk_version",
+              "checkpoint.page_kit.store_profile.repair_waiver",
+              "checkpoint.page_kit.store_profile.waive",
+              "checkpoint.built_output.upsell_selector_scope.repair_target",
+              "checkpoint.built_output.upsell_selector_scope.align_store_profile",
+              "checkpoint.built_output.upsell_selector_scope.align_sdk_version",
+              "checkpoint.built_output.upsell_selector_scope.repair_waiver",
+              "checkpoint.built_output.upsell_selector_scope.waive",
+              "checkpoint.polish.hidden_eager_media.capture",
+              "checkpoint.polish.hidden_eager_media.install_browser",
+              "checkpoint.polish.hidden_eager_media.repair",
+              "checkpoint.polish.hidden_eager_media.repair_authority",
+              "checkpoint.polish.hidden_eager_media.local_proof_rebuild",
+              "checkpoint.polish.hidden_eager_media.waive",
+              "unknown"
+            ]
+          }
+        },
+        "gates": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "state"
+            ],
+            "properties": {
+              "id": {
+                "enum": [
+                  "doctor",
+                  "prepare_build",
+                  "theme_gate",
+                  "polish_gate",
+                  "page_kit.sdk_version",
+                  "page_kit.store_profile",
+                  "built_output.upsell_selector_scope",
+                  "polish.hidden_eager_media",
+                  "unknown"
+                ]
+              },
+              "state": {
+                "enum": [
+                  "pass",
+                  "blocked",
+                  "waived",
+                  "not_applicable",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "qa": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "verdict_id",
+            "disposition",
+            "binding",
+            "publish_state"
+          ],
+          "properties": {
+            "verdict_id": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[A-Za-z0-9_-]{1,64}$"
+            },
+            "disposition": {
+              "enum": [
+                "ready",
+                "ready_with_exceptions",
+                "blocked",
+                "unknown"
+              ]
+            },
+            "binding": {
+              "enum": [
+                "matching",
+                "unconfirmed"
+              ]
+            },
+            "publish_state": {
+              "enum": [
+                "skipped",
+                "ok",
+                "failed",
+                "unknown"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/next-campaigns-build/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-build
-version: 1.0.2
+version: 1.0.3
 description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
 ---
 
 # Next Campaigns Build
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 ## Recommended Build Loop
 
 For campaign builds, follow **build → independent review → repair → verification**.

package/skills/next-campaigns-os/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-os
-version: 1.0.16
+version: 1.0.17
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
 # Campaigns OS
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this skill to orient a campaign build, run preflight, decide the next stage, and keep the lifecycle honest.
 
 ## Public Lifecycle Boundary
@@ -32,7 +48,7 @@ Workflow:
 7. If doctor's `next` block says `doctor-blocked` or `prepare-build` (it names the same stage `campaigns-os next` would), stop and resolve the named blockers.
 8. If doctor returns `build`, hand off with `campaigns-os next build --packet <packet>` and follow `next-campaigns-build`'s recommended **build → independent review → repair → verification** loop.
 9. After build, require polish and a preview deploy before QA. During Polish,
-   install the package-owned browser once with `npm run qa:install-browser`,
+   install the package-owned browser once with `npx campaigns-os qa install-browser`,
    serve the current build, and run `campaigns-os polish capture --packet <p> --base-url <served-build-url>` before recording a terminal Polish status.
    The package-owned producer attaches `visual_review.page_load`; never
    hand-author it. Nonwaivable incomplete evidence blocks. A complete hidden
@@ -41,7 +57,7 @@ Workflow:
    Doctor/next report `ready_with_waivers`; QA
    retains each attributed exception as `ready_with_exceptions`, and one
    exception never suppresses another blocker.
-10. Run the package-owned proof path in sequence: ensure `npm run qa:install-browser` has completed, run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common`.
+10. Run the package-owned proof path in sequence: ensure `npx campaigns-os qa install-browser` has completed, run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common`.
 11. Treat typed-card proof coverage as the control. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs checkout, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation.
 12. Discuss launch only from recorded build, polish, deploy, browser QA, and test-order evidence, or from explicit blockers.
 

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.0
+version: 2.0.1
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
 # Next Campaigns OS Setup
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this skill when the Build Packet doctor says setup is required before assembly.
 
 Responsibilities:

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-polish
-version: 1.1.1
+version: 1.1.2
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
 # Next Campaigns Polish
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this after build has produced a runnable page-kit campaign.
 
 Theme gate: `campaigns-os next polish` blocks when theme inspect found a
@@ -33,7 +49,7 @@ Responsibilities:
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
 - If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
 - Before recording a terminal Polish status, install the package-owned browser
-  once with `npm run qa:install-browser`, serve the current build, and run
+  once with `npx campaigns-os qa install-browser`, serve the current build, and run
   `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`.
   The package captures every mapped route at fixed desktop/mobile viewports and
   attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,

package/skills/next-campaigns-qa/SKILL.md

@@ -1,26 +1,42 @@
 ---
 name: next-campaigns-qa
-version: 1.3.1
+version: 1.3.2
 description: Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
 # Next Campaigns QA
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 Use this after the campaign has a preview or production URL and the assembly report records build and polish status. The public v0 runner is Node/npm-based, with an owned Playwright browser pass:
 
 ```bash
-npm run qa:install-browser
-npm run campaigns-os -- qa resolve --packet campaign-runtime.build.json
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url>
+npx campaigns-os qa install-browser
+npx campaigns-os qa resolve --packet campaign-runtime.build.json
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url>
 # Fixture-driven migration parity proof. Publishes to the QA portal by default.
-npm run campaigns-os -- qa parity --fixture <parity-fixture.json> --scenario <scenario-id> --base-url <preview-url>
+npx campaigns-os qa parity --fixture <parity-fixture.json> --scenario <scenario-id> --base-url <preview-url>
 # Browser QA + typed-card proof. Publishes to the QA portal by default and prints the portal link.
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common
 # Offline / dev / CI only: keep the verdict local
-npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common --no-post-verdict
+npx campaigns-os qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common --no-post-verdict
 ```
 
-`npm run qa:install-browser` is part of the standard QA sequence. Run it once
+`npx campaigns-os qa install-browser` is part of the standard QA sequence. Run it once
 after install/update before using `--browser` or `--test-order`; do not skip it
 unless the local Playwright browser binary is already installed.
 

package/skills.json

@@ -15,7 +15,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.16",
+      "version": "1.0.17",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -23,7 +23,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -31,7 +31,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.2",
+      "version": "1.0.3",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -39,7 +39,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.1",
+      "version": "1.1.2",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -47,7 +47,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.1",
+      "version": "1.3.2",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."