@nextcommerce/campaigns-os 1.37.2 → 1.41.2

package/schemas/campaigns-os-effects.v1.schema.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-effects.v1.schema.json",
+  "title": "Campaigns OS Declared Command Effects v1",
+  "description": "The shape of contracts/effects.v1.json: one row per supported invocation — a command, its subcommand, and the flag combination that changes what the invocation does to the world — stating what it writes, what it sends, the MCP-style annotations a tool face would carry, the effect tier, and the name of the node:test case that proves the row. The claim a row makes is two-sided and both sides are tested: nothing the row does not declare may change, and every declared effect whose `observed_in` names a condition must be seen in it. An effect the offline fixture cannot reach carries an empty `observed_in` and a `not_observed_reason`. Read this with docs/effects.md; scripts/check-effects.mjs enforces the parts a schema cannot (coverage of the supported CLI surface, and the existence of every named test case).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "contract_version", "vocabulary", "rows"],
+  "properties": {
+    "schema": {
+      "const": "campaigns-os-effects/v1",
+      "description": "A consumer should refuse a payload whose schema it does not recognize rather than reading the fields it happens to know."
+    },
+    "_note": { "type": "string" },
+    "contract_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "The contract's own version, independent of the package's surface_version: adding a row is additive, changing a row's declared effect is not."
+    },
+    "vocabulary": {
+      "type": "object",
+      "description": "The words the rows use, defined once. A reader must not have to infer what `tier: \"C\"` or `{lifecycle-journal}` means from the rows that happen to use them.",
+      "additionalProperties": false,
+      "required": ["annotations", "tiers", "locations", "conditions", "effect_changing_flags", "test_scope", "observed_in", "preflight"],
+      "properties": {
+        "annotations": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["readOnlyHint", "destructiveHint", "openWorldHint", "idempotentHint"],
+          "properties": {
+            "readOnlyHint": { "type": "string" },
+            "destructiveHint": { "type": "string" },
+            "openWorldHint": { "type": "string" },
+            "idempotentHint": { "type": "string" }
+          }
+        },
+        "tiers": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["none", "A", "B", "C", "_ranking"],
+          "properties": {
+            "none": { "type": "string" },
+            "A": { "type": "string" },
+            "B": { "type": "string" },
+            "C": { "type": "string" },
+            "_ranking": { "type": "string" }
+          }
+        },
+        "locations": {
+          "type": "object",
+          "description": "The location tokens a row's write paths may use. A path pattern is relative to the token it opens with.",
+          "minProperties": 1,
+          "additionalProperties": { "type": "string" }
+        },
+        "conditions": {
+          "type": "object",
+          "description": "The five conditions every row is exercised under. The fifth, persisted_consent, is not a variant of the other four: it is the one that does not take the row's word for whether telemetry consent is on.",
+          "additionalProperties": false,
+          "required": ["no_session", "ambient_session", "stale_session", "lifecycle_log", "persisted_consent"],
+          "properties": {
+            "no_session": { "type": "string" },
+            "ambient_session": { "type": "string" },
+            "stale_session": { "type": "string" },
+            "lifecycle_log": { "type": "string" },
+            "persisted_consent": { "type": "string" }
+          }
+        },
+        "effect_changing_flags": {
+          "type": "array",
+          "description": "The flags that change what an invocation does to the world. Every one of them that appears on a CLI help usage line owes a row of its own; scripts/check-effects.mjs refuses the file when one does not have it. A flag that only changes the output shape (--json, --report) is deliberately absent.",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^--[a-z0-9-]+$" }
+        },
+        "test_scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["full", "preflight"],
+          "properties": { "full": { "type": "string" }, "preflight": { "type": "string" } }
+        },
+        "observed_in": { "type": "string" },
+        "preflight": { "type": "string" }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "$defs": {
+    "condition": {
+      "enum": ["no_session", "ambient_session", "stale_session", "lifecycle_log", "persisted_consent"]
+    },
+    "observed_in": {
+      "type": "array",
+      "description": "The conditions in which the effect test MUST see this effect. Empty declares an effect the offline fixture cannot reach, and then `not_observed_reason` is required.",
+      "items": { "$ref": "#/$defs/condition" },
+      "uniqueItems": true
+    },
+    "row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "subcommand", "flags", "annotations", "tier", "writes", "sends", "effect_test", "test_scope", "notes"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The top-level command, or the reserved `*refused*` for an invocation refused before its handler runs."
+        },
+        "subcommand": {
+          "description": "The subcommand as the help text spells it (`policy set` is one subcommand, not a subcommand and a flag), or null.",
+          "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }]
+        },
+        "flags": {
+          "type": "array",
+          "description": "The effect-changing flag combination this row is about. Empty is the base form. Flags that do not change what the invocation does to the world (--json, --report) are deliberately absent.",
+          "items": { "type": "string", "pattern": "^--[a-z0-9-]+$" },
+          "uniqueItems": true
+        },
+        "annotations": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["readOnlyHint", "destructiveHint", "openWorldHint", "idempotentHint"],
+          "properties": {
+            "readOnlyHint": { "type": "boolean" },
+            "destructiveHint": { "type": "boolean" },
+            "openWorldHint": { "type": "boolean" },
+            "idempotentHint": { "type": "boolean" }
+          }
+        },
+        "tier": { "enum": ["none", "A", "B", "C"] },
+        "writes": { "type": "array", "items": { "$ref": "#/$defs/write" } },
+        "sends": { "type": "array", "items": { "$ref": "#/$defs/send" } },
+        "effect_test": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The exact name of the node:test case in src/effects.test.mjs that proves this row. check-effects.mjs refuses a row whose case is not there."
+        },
+        "test_scope": { "enum": ["full", "preflight"] },
+        "preflight": { "$ref": "#/$defs/preflight" },
+        "notes": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Why the row says what it says, in a consumer's terms. A preflight row states what it cannot reach offline and what the case proves instead."
+        }
+      },
+      "if": { "properties": { "test_scope": { "const": "preflight" } }, "required": ["test_scope"] },
+      "then": {
+        "description": "A preflight row declares its allowances. The converse — a `full` row that carries them — is reported by scripts/check-effects.mjs, which can say which row it is.",
+        "required": ["preflight"],
+        "properties": { "preflight": { "$ref": "#/$defs/preflight" } }
+      }
+    },
+    "preflight": {
+      "type": "object",
+      "description": "What the preflight itself may do, declared independently of the effects the row declares for the invocation that gets past it. Without this, a write declared for the success path ({home}/** for a minted credential) also licensed the refusal to write anywhere under the home directory, and a destination a loopback receiver only stands in for licensed any request path at all.",
+      "additionalProperties": false,
+      "required": ["may_write", "may_contact"],
+      "properties": {
+        "may_write": {
+          "type": "array",
+          "description": "The ONLY paths the preflight may write, each a location token or a path under one. A pattern spanning segments (**) is refused by scripts/check-effects.mjs: an allowance that licenses a subtree licenses the home directory the preflight must not touch.",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "may_contact": {
+          "type": "array",
+          "description": "The exact request paths the loopback receiver may see, matched literally against the request path. Empty means the preflight contacts nothing.",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "write": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "when", "observed_in"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A glob pattern (`*` within one segment, `**` across segments) opening with a location token from vocabulary.locations."
+        },
+        "when": { "type": "string", "minLength": 1 },
+        "observed_in": { "$ref": "#/$defs/observed_in" },
+        "not_observed_reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "send": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["destination", "what", "when", "requires_consent", "observed_in"],
+      "properties": {
+        "destination": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The endpoint, with the same location tokens. A destination of the form `{proxy-base}/<path>` pins the request path down, so the test can assert the declared destination IS the one contacted."
+        },
+        "what": { "type": "string", "minLength": 1 },
+        "when": { "type": "string", "minLength": 1 },
+        "requires_consent": {
+          "type": "boolean",
+          "description": "True when Run Telemetry consent gates the send. The effect test runs such a row with consent ON and a loopback receiver, so 'nothing was sent' can never be an artefact of consent being off."
+        },
+        "observed_in": { "$ref": "#/$defs/observed_in" },
+        "not_observed_reason": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/campaigns-os-readback.v2.schema.json

@@ -0,0 +1,267 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-readback.v2.schema.json",
+  "title": "Campaigns OS Run-Artifact Readback v2",
+  "description": "The machine-readable projection `campaigns-os readback <target> --json` writes to stdout. It serializes exactly what the rendered text view computes over a run's already-emitted artifacts (Build Packet, doctor output, build context, assembly report, QA verdict, findings export) and adds no interpretation the text view does not also carry. The readback is read-only: it writes nothing under the target, starts no process, touches no network, and records no lifecycle entry. v2 differs from v1 in one field's meaning: staleness is assessed PER ARTIFACT, and the aggregate `stale` is true when ANY loaded artifact is stale, where v1 compared only the newest artifact and so reported a set fresh whenever its newest member was. Field semantics and the exact `clean` rule live in docs/readback.md; that document and this schema move together. A consumer that recognizes v2 accepts and preserves unknown additive properties without interpreting them.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "artifacts",
+    "packet_selection",
+    "staleness",
+    "doctor",
+    "skip_cascades",
+    "divergences",
+    "clean"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-readback/v2",
+      "description": "A consumer should refuse a payload whose schema_version it does not recognize rather than reading the fields it happens to know."
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "One record per artifact the readback projected, in the fixed render order (packet, doctor, context, report, qa_verdict, findings), restricted to the keys the caller asked for. The artifact's own parsed contents are deliberately absent: a consumer that wants an artifact's payload reads that artifact, so this projection never becomes an unversioned mirror of every upstream schema.",
+      "items": { "$ref": "#/$defs/artifact_row" }
+    },
+    "packet_selection": {
+      "description": "How the projected Build Packet was chosen, or null when a programmatic caller built a payload without a selection record. The CLI always supplies one.",
+      "oneOf": [{ "$ref": "#/$defs/packet_selection" }, { "type": "null" }]
+    },
+    "staleness": {
+      "description": "The per-artifact freshness assessment, or null when a programmatic caller built a payload without one. The CLI always supplies one.",
+      "oneOf": [{ "$ref": "#/$defs/staleness" }, { "type": "null" }]
+    },
+    "doctor": { "$ref": "#/$defs/doctor_summary" },
+    "skip_cascades": {
+      "type": "array",
+      "description": "Skipped QA assertions grouped by the failure that blocked them, derived from each skipped assertion's evidence.blocked_by. One record per distinct blocker, in first-seen order. Empty when no QA verdict loaded or none of its assertions were skipped. The grouping is the readback's own projection layer.",
+      "items": { "$ref": "#/$defs/skip_cascade" }
+    },
+    "divergences": {
+      "type": "array",
+      "description": "Where two artifacts record different states for one stage: the assembly report calls a stage completed while the QA verdict fails an assertion whose id is namespaced to that stage. One record per stage, in the order the failures were seen. The readback reports the disagreement and does not adjudicate it. This too is the readback's own layer.",
+      "items": { "$ref": "#/$defs/divergence" }
+    },
+    "clean": {
+      "type": "boolean",
+      "description": "True only when every artifact the readback found is loaded or absent (never unreadable or unrecognized), staleness is computable and NO loaded artifact is stale, staleness.unparseable_keys is empty (no loaded artifact recorded an age the readback could not read), divergences is empty, and doctor.error_count is zero. A readback-integrity flag, not a verdict: a blocked QA verdict whose artifacts all read cleanly is still clean, because the readback saw exactly what Campaigns OS recorded. docs/readback.md states the rule and its limits."
+    }
+  },
+  "$defs": {
+    "artifact_key": {
+      "type": "string",
+      "enum": ["packet", "doctor", "context", "report", "qa_verdict", "findings"]
+    },
+    "utc_timestamp": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "ISO-8601 UTC at second precision with a Z suffix, rendered by the same formatter the text view uses so both modes name the same instant identically."
+    },
+    "artifact_row": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["key", "path", "state", "detail"],
+      "properties": {
+        "key": { "$ref": "#/$defs/artifact_key" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The path the readback read, as resolved from the target root, a --<artifact> override, or — for packet — Build Packet discovery. --example reports the bundled sample's paths relative to the package root so the sample's output is identical wherever the package is installed."
+        },
+        "state": {
+          "type": "string",
+          "enum": ["loaded", "absent", "unreadable", "unrecognized"],
+          "description": "loaded: read and recognized. absent: no file at that path. unreadable: the bytes could not be read or parsed (over the 32 MiB read bound, not UTF-8, not JSON). unrecognized: parsed, but not a shape this readback projects."
+        },
+        "detail": {
+          "type": "string",
+          "description": "The readback's explanation for a non-loaded state, or — for a loaded artifact named in staleness.unparseable_keys — the shape of the generated_at value that did not parse, so a consumer reading artifacts alone can see that this artifact's age was never established. The value itself is deliberately not reproduced here. The empty string for every other loaded artifact and for an absent one."
+        }
+      }
+    },
+    "packet_selection": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["mode", "signal", "selected", "candidates_considered", "rejected"],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["explicit", "default", "discovered"],
+          "description": "explicit: the caller passed --packet. default: the chosen packet is the default-named campaign-runtime.build.json, including a target with no packet at all, where the default path is still the path reported absent. discovered: freshness selected a suffixed packet."
+        },
+        "signal": {
+          "type": "string",
+          "enum": ["explicit", "sole_candidate", "generated_at", "none"],
+          "description": "What decided it. Freshness is the packet's own recorded generated_at, never the file's modification time: an mtime is rewritten by a clone, a checkout, or a copy without any run having recorded anything, so content-only selection keeps discovery a pure function of the bytes on disk."
+        },
+        "selected": {
+          "description": "The file name discovery chose, or null when no discovery chose one (the explicit and none signals). The full path is the packet row's path in artifacts.",
+          "type": ["string", "null"]
+        },
+        "candidates_considered": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "The file names of the valid candidates discovery compared, default-first then name order. Empty for explicit mode, where no discovery runs."
+        },
+        "rejected": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/rejected_candidate" },
+          "description": "Candidates discovery skipped. Root-level files matching the packet naming land here when they did not parse, were not an object, or did not declare a recognized packet schema_version. When no valid root candidate exists, a packet sitting only at .campaign-runtime/campaign-runtime.build.json is recorded here too: that sidecar location is not a discovery candidate, and the reason tells the caller to pass --packet."
+        }
+      }
+    },
+    "rejected_candidate": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["path", "reason"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "staleness": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "computable",
+        "stale",
+        "stale_keys",
+        "unparseable_keys",
+        "artifacts",
+        "newest_key",
+        "head_time",
+        "head_detail",
+        "artifact_times"
+      ],
+      "properties": {
+        "computable": {
+          "type": "boolean",
+          "description": "True when at least one loaded artifact carried a parseable generated_at AND the checkout's HEAD reflog was readable."
+        },
+        "stale": {
+          "type": "boolean",
+          "description": "True when ANY loaded artifact's generated_at predates the last recorded HEAD movement. This is the v1 -> v2 change of meaning: v1 compared only the newest artifact, so one regenerated artifact reported the whole set fresh. Always false when computable is false; absence of the signal is not evidence of freshness."
+        },
+        "stale_keys": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/artifact_key" },
+          "description": "The stale artifact keys, in the fixed render order. Empty when nothing is stale or the comparison is not computable."
+        },
+        "unparseable_keys": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/artifact_key" },
+          "description": "The loaded artifacts that RECORDED a generated_at this readback could not parse, in the fixed render order. Their age was never established — they are neither fresh nor stale, they are absent from artifacts and artifact_times, and clean is false while this list is non-empty, because an unknown age must never read as a fresh one. Each one's artifact row carries the shape of the refused value in its detail. An artifact that carries NO generated_at key at all is a different case: it recorded no age to check, so it is absent from this list and is not by itself unclean (though with no other artifact carrying one, the comparison is not computable). Independent of computable and stale, which keep their meanings: a set whose only comparable artifact is fresh still reports stale false."
+        },
+        "artifacts": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/artifact_freshness" },
+          "description": "Every loaded artifact that carried a parseable generated_at, keyed by artifact key, in render order. An artifact with no parseable generated_at is neither fresh nor stale and is absent from this map; if it is the only artifact, the assessment is not computable. Where it recorded a generated_at that did not parse, unparseable_keys names it."
+        },
+        "newest_key": {
+          "description": "The artifact key holding the newest generated_at, or null when not computable. Information only in v2: it no longer decides the aggregate.",
+          "oneOf": [{ "$ref": "#/$defs/artifact_key" }, { "type": "null" }]
+        },
+        "head_time": {
+          "description": "The last recorded HEAD movement, or null when the reflog gave no usable time.",
+          "oneOf": [{ "$ref": "#/$defs/utc_timestamp" }, { "type": "null" }]
+        },
+        "head_detail": {
+          "type": "string",
+          "description": "Why head_time is null; the empty string when it is not."
+        },
+        "artifact_times": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/utc_timestamp" },
+          "description": "Every loaded artifact's parseable generated_at, keyed by artifact key. Carried unchanged from v1 for consumers that already read it; artifacts carries the same instants plus each one's verdict."
+        }
+      }
+    },
+    "artifact_freshness": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["generated_at", "stale"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/utc_timestamp" },
+        "stale": {
+          "type": "boolean",
+          "description": "True when the last recorded HEAD movement is later than this artifact's generated_at. False when there is no HEAD signal to compare against."
+        }
+      }
+    },
+    "doctor_summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["present", "status", "error_count", "warning_count", "warning_groups"],
+      "properties": {
+        "present": {
+          "type": "boolean",
+          "description": "Whether a doctor output loaded. When false, status is null and both counts are 0: those zeros record an absence, not an observation."
+        },
+        "status": {
+          "type": ["string", "null"],
+          "description": "Doctor's own status string, unreinterpreted."
+        },
+        "error_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The length of doctor's errors list (0 when the field is missing or not a list)."
+        },
+        "warning_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of object-shaped warnings grouped below."
+        },
+        "warning_groups": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["contract-static", "repo-observed"],
+          "description": "The readback's own two-way grouping of doctor warnings, carrying each warning as doctor wrote it. The labels are the readback's projection layer, not doctor's vocabulary.",
+          "properties": {
+            "contract-static": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Codes under the frontmatter.* prefixes. These restate the template family's shared frontmatter contract and repeat verbatim on every doctor pass while that contract is in force. Their persistence does not mean a flagged value is still unfixed, and their disappearance is not how a fix is confirmed. A gate must not treat these as repository state."
+            },
+            "repo-observed": {
+              "type": "array",
+              "items": { "type": "object" },
+              "description": "Every other code: not in the contract-static table, so its message reflects this repository, spec, or build as doctor saw it."
+            }
+          }
+        }
+      }
+    },
+    "skip_cascade": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["blocked_by", "families"],
+      "properties": {
+        "blocked_by": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The recorded blocking assertion, or the literal \"(no blocked_by recorded)\" when the verdict named none."
+        },
+        "families": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The skipped assertions' families, falling back to the assertion id and then to \"(unnamed)\"."
+        }
+      }
+    },
+    "divergence": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["stage", "assertion_ids"],
+      "properties": {
+        "stage": { "type": "string", "minLength": 1 },
+        "assertion_ids": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "The failing QA assertion ids attributed to that stage."
+        }
+      }
+    }
+  }
+}

package/skills/campaign-lifecycle-orientation/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: campaign-lifecycle-orientation
+version: 1.0.3
+description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
+---
+
+Bundle revision: 1.41.2+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.41.2+skills.1`
+from the campaign's Page Kit folder, where it runs the project's pinned copy and
+never installs one, at the start of each task. Start a fresh session if it
+reports `mismatch`: this text is already in your context and is never re-read
+while the CLI on disk can move under it. If the output has no `Skills revision:`
+line (no `revision_check` under `--json`), a campaigns-os older than this check
+answered; follow none of its actions and run the pinned copy.
+
+# Campaign lifecycle orientation
+
+Use this skill to place Build Packet, Assembly Report and doctor language in the
+pipeline and read what a run already recorded. It teaches interpretation only.
+It advances no stage, and nothing in it is permission to run a command that
+writes.
+
+The effect class in each parenthetical below is the declared row of
+`contracts/effects.v1.json` (`none` < `B` writes < `A` sends < `C`
+destructive). Read that file, not this text, when an exact path or endpoint
+matters.
+
+## Cite only the supported surface
+
+For Campaigns OS facts, cite `contracts/supported-surface.json` and the entries
+it names — `CONTEXT.md`, `CHANGELOG.md`, `skills.json`, the `contracts/`,
+`schemas/` and `docs/` entries listed there, and the published CLI path. Never
+cite `src/` or `scripts/`: those are implementation and may change without a
+supported-surface bump, so a reader cannot check them and a rename would not
+reach this text. `docs/supported-surface.md` is the prose twin of that list.
+
+Identity comes from the tool, not from a file beside the session.
+`campaigns-os tooling status --json` (tier `B`: its only write is the
+command-lifecycle journal) reports the install mode, the version, and a source
+commit when one is derivable. Quote what it printed. Do not derive the answer
+from Git HEAD, from the word "latest", or from prose in a checkout.
+
+## Start with the shared vocabulary
+
+`CONTEXT.md` is the glossary kept reconciled against the code, and it separates
+public lifecycle language from internal implementation language. A
+**CampaignSpec** is the JSON campaign contract; current packets use CampaignSpec
+4.2, whose funnel structure lives in `funnels[]`
+(`schemas/campaign-spec.v4.schema.json`). A **Build Packet** is the assembly
+handoff that wraps the spec without replacing it (`docs/build-packet.md`). An
+**Assembly Report** is the machine-readable record of lifecycle progress.
+
+A **Design Source Package** is the normalized source bundle Campaigns OS writes
+when it prepares a build; a material source-reference refresh creates a new one
+rather than editing one in place. A **Readiness Checkpoint** is an
+artifact-backed gate, resumable across runs, passed on evidence or by a
+recorded and attributed waiver. **Partial-source** scope is the documented case
+where only part of a campaign's source is supplied: a declared input state, not
+a degraded run, so treat the absent part as absent evidence rather than
+inferring it.
+
+## Place the artifacts in the pipeline
+
+Campaigns OS normalizes a CampaignSpec into `campaign-runtime.build.json`
+(`campaign-runtime-build-packet/v0`). **Page Kit** is the static-site builder
+for campaign funnels. Under the target repository's `.campaign-runtime/`
+Campaigns OS also writes the Build Context, the Assembly Report, the doctor
+output sidecar, theme evidence and normalized inputs
+(`docs/campaigns-os-build-flow.md`). Its `_site/` output is deployed by a
+separate system, and QA then tests a deployed URL
+(`docs/qa-and-test-orders.md`).
+
+Keep the two identities apart. The **Map ID** identifies the saved campaign map
+and keys QA evidence storage; the **public route slug** is the shopper-facing
+path segment. Read both from the packet and never substitute one for the other.
+
+Campaign pages are typed. The page-type vocabulary is `presell`, `landing`,
+`select`, `checkout`, `upsell`, `downsell` and `thankyou`; `select` is where a
+shopper chooses a package before checkout. Use the spec's own term for a page
+rather than describing it.
+
+## Read doctor as a gate
+
+**Doctor** is the lifecycle gate that must pass before the stage ladder
+proceeds. It checks the packet, its CampaignSpec, the artifacts and the built
+output, and its ordered check registry records what ran. When blocking errors
+exist the result is not OK, names the errors, and points the next step at
+collecting or correcting input. `campaigns-os doctor --packet <packet> --json`
+(tier `none`: inspection is the default, and without `--write` it leaves the
+target byte-identical) is the inspection form.
+
+Read doctor's recorded result, not a process exit code. Exit codes are knowable
+only from implementation files this skill may not cite, so do not branch on one.
+
+## Read the stage record
+
+`campaigns-os next --packet <packet> --json` (tier `A`: it captures a progress
+snapshot under the target and, under Run Telemetry consent, POSTs that
+observation off the machine) reads the recorded state and names the next
+incomplete stage among `setup`, `build`, `polish`, `deploy` and `qa`. That is a
+writing, potentially sending command. If all you need is where the run stands,
+prefer the readback below.
+
+The stage called `build` at the CLI is stored under `stages.assembly`. The
+Assembly Report's picker treats statuses beginning `completed` and statuses
+beginning `skipped` as terminal. Build evidence carries `build_fingerprint`, an
+identifier for the exact built state. Polish evidence must classify every
+unresolved issue; the `repair_needed` class means the built output still needs
+work, and the documented polish gate holds deploy and QA until the issue is
+repaired, reclassified or covered by a structured waiver.
+
+Where these artifacts already exist for a target, do not open them first.
+`campaigns-os readback <target-repo-root> --json` (tier `none`: it writes
+nothing, not even a lifecycle entry, starts no process and touches no network)
+projects their loaded state, their per-artifact staleness against the
+checkout's HEAD reflog, the doctor warning grouping, the skip cascades and any
+cross-artifact divergence into one `campaigns-os-readback/v2` object.
+`docs/readback.md` and `schemas/campaigns-os-readback.v2.schema.json` say what
+each field means. Cite that projection as the evidence base and open the
+artifacts themselves only to drill into what it names. This orientation
+explains what the artifacts mean; it is not a licence to re-derive the
+projection's staleness or warning grouping by hand.
+
+The **Theme Gate** decides whether the generated brand layer is acceptable for
+commerce pages. It is not advice: `next` and QA consume the result and stop
+later stages when it is blocked. An applied layer or a recorded waiver with a
+reason is the supported way through, and downstream evidence keeps the waiver
+visible (`docs/brand-theme-bridge.md`).
+
+## Avoid the two-worlds mistake
+
+Store themes and Page Kit campaign funnels are not one build surface, and
+conflating them is the most expensive orientation error available here. This
+repository documents Page Kit as the funnel target and describes the deployment
+of its static output. It does not define the separate store-theme publishing
+stack at all, so that half of the distinction is unverified from here — say so
+rather than filling it in. A claim about store-theme publishing cannot be
+sourced from this surface, and an answer that quietly treats a funnel artifact
+as theme evidence (or the reverse) will read as authoritative while resting on
+nothing.
+
+For Page Kit routes, read the packet's per-page target projection — the
+resolved output path for that page — rather than copying producer directories.
+A page needs a **permalink**, an explicit public route assigned to it. Routing
+surprises are not harmless: `prepare-build` can report
+`PAGE_KIT_TARGET_CONFLICT` when two routes project to one terminal filename
+(`docs/build-packet.md`). The machine-readable build summary is the evidence to
+inspect; a build command that exited successfully does not establish correct
+routing.
+
+Two further routing error codes an earlier version of this text named were
+dropped rather than re-sourced: they appear only in implementation files, so a
+reader could not verify them. Inspect the build summary and report what it says.
+
+## Name the current skill set
+
+This repository publishes its own skill set and names it in `skills.json`. Use
+the id the manifest publishes — the Build Packet setup skill is
+`next-campaigns-os-setup` — and read the manifest rather than remembering a
+name; an older name for the same skill is a stale reference.
+
+## Capability boundary
+
+This skill conveys interpretation knowledge only. It authorizes no lifecycle
+command and no change to campaign state. What any supported invocation may do
+is declared per row in `contracts/effects.v1.json` and explained in
+`docs/effects.md`; widening it is a pull request that changes a row of that
+file, never a decision made in a session.
+
+An operator-supplied checkout is inspect-only. Do not run `git pull`, `git
+fetch`, checkout, reset, clean or any other Git mutation against it; a baseline
+change is a reviewed change, not a conversational one. Name any suggested
+mutation as work for an authorized human and do not perform it through this
+skill.