@se-studio/skills 1.5.10 → 1.5.11

package/CHANGELOG.md

@@ -1,11 +1,16 @@
 # @se-studio/skills
 
+## 1.5.11
+
+### Patch Changes
+
+- Document smoke/deploy failure playbook and refuse-customer-patches guardrails (agent-session Step 3b).
+
 ## 1.5.10
 
 ### Patch Changes
 
 - Document lockfile sync enforcement (scripts, CI snippet, deps-update and smoke-test skill updates).
-- 2359f69: Add `site-workflows-stale-files-cleanup` skill and `references/stale-files-cleanup/` for repository hygiene audits on SE Studio marketing sites.
 
 ## 1.5.8
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.5.10",
+  "version": "1.5.11",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/references/agent-session/customer-agents-block.md

@@ -22,6 +22,16 @@ Before non-trivial code, run the placement checklist (in the skill). Summary:
 
 If the checklist says **core**, stop and switch to core-first mode — do not patch `@se-studio` behaviour in this repo.
 
+### Deploy smoke failed?
+
+Do **not** change `baseUrl`, discovery routes, or add `getRequestBaseUrl()` to unblock Vercel Deployment Checks. That fix belongs in `@se-studio/site-check` (core-first).
+
+1. Follow the smoke/deploy failure playbook in `se-core-product` — `packages/skills/references/agent-session/smoke-deploy-failure-playbook.md`
+2. Bump `@se-studio/site-check@2.9.4+` after npm publish (`discovery.urlOrigin: auto`)
+3. Customer-only: curate new URLs in `smoke.cases.json` when CMS routes go live — not package assertion hacks
+
+Record `placement.decision` in `work/active/<feature>.yaml` before smoke/server-config commits aimed at deploy smoke.
+
 ### Core release order
 
 When work depends on a new `@se-studio/*` npm release:

package/references/agent-session/manifest.template.yaml

@@ -19,6 +19,8 @@ placement:
   rationale: One-site hero layout tied to OM1 Figma
   extract_to_core: null # pending | null
   extract_rationale: null
+  # Required before smoke/server-config commits for deploy-smoke goals (agent-session Step 3b):
+  # smoke_edit: null # curated-urls | blocked-on-core | defer-extract
 
 blocked_on: null # e.g. "@se-studio/core-ui@2.1.0"
 cms_session: null # set to feature slug when doing parallel CMS edits

package/references/agent-session/refuse-customer-patches.md

@@ -0,0 +1,58 @@
+# Refuse customer patches (site-first guardrails)
+
+Agents in **site-first** mode must **refuse** customer-repo changes that belong in **`se-core-product`** (`@se-studio/*`), unless the user explicitly approves **`defer-extract`** in the manifest with `extract_to_core: pending` and a dated extraction plan.
+
+Run this table **in addition to** the placement checklist (`site-workflows-agent-session` Step 3) when the task touches smoke, deploy checks, shared packages, or infra.
+
+## Refusal triggers
+
+| Symptom, file, or request | Correct owner | Agent action (site-first) |
+|---------------------------|---------------|---------------------------|
+| Deploy / `smoke-test:live` failure after bumping `@se-studio/*` | **core** — fix package behaviour | **Stop.** Switch to core-first or set `blocked_on: "@se-studio/<pkg>@<version>"`. Customer only bumps after npm publish. |
+| Discovery smoke (`llms.txt`, `markdown-index.txt`, `cms.txt`, `site-info.md`) origin mismatch on `*.vercel.app` | **core** — `@se-studio/site-check` (`discovery.urlOrigin`) | **Refuse** per-request origin hacks (`getRequestBaseUrl`, `headers()` for `baseUrl`). Bump `site-check@2.9.4+`. |
+| Patching `@se-studio/site-check` expectations in app code | **core** `site-check` | **Refuse.** Open core PR + changeset. |
+| Forking converter / link logic already in `contentful-rest-api` | **core** | **Refuse.** Fix converter or API in core. |
+| `pnpm patch`, `patchedDependencies`, or overrides to fork `@se-studio/*` | **forbidden** | **Refuse** (see root `AGENTS.md`). |
+| New smoke assertion that should apply to all marketing sites | **core** `site-check` | **Refuse** site-only assertion helpers; extend site-check. |
+| `route-build-policy.json` change to hide a core regression (e.g. allow new `ƒ` on CMS routes) | **core** + site routing fix | **Refuse** policy-only workaround; fix why route went dynamic. |
+
+## Allowed customer-only smoke edits
+
+| Change | When |
+|--------|------|
+| Add/remove **curated URLs** in `smoke.cases.json` | New CMS pages, article types, tags/people go live — follow `se-marketing-sites-smoke-test-setup` |
+| Set `discovery` flags to `false` | Site-specific infra (e.g. CloudFront not routing discovery paths yet) |
+| `cmsIntegrity.routing` mapping | Per-site URL calculators — not a package bug |
+| Security **probe** cases (`category: probe`) | Site-specific hardening (see brightline reference) |
+
+## `defer-extract` (escape hatch)
+
+Use only when the user **explicitly** accepts short-term customer code with a core extraction ticket:
+
+1. Manifest `placement.decision: defer-extract`
+2. `extract_to_core: pending` + `extract_rationale` (what moves to which package)
+3. Add `work/tracker.yaml` rollout or `attention` item if multi-site
+4. **Do not** merge to customer `develop` if it blocks other sites on a shared package fix
+
+## Manifest gate
+
+Before committing customer changes to any of:
+
+- `smoke.cases.json`, `route-build-policy.json`
+- `src/lib/server-config.ts`, discovery route handlers (`llms.txt`, `markdown-index.txt`, …)
+- `scripts/smoke-test-*.ts`, `.github/workflows/deployment-smoke.yml`
+
+…when the **stated goal** is “fix deploy smoke” or “fix site-check failure”:
+
+1. Record `placement.decision` and `placement.rationale` in `work/active/<feature>.yaml`
+2. If decision is `core`: **do not commit customer workaround** — switch mode
+3. If decision is `customer`: user must confirm in chat (legitimate site-only URL curation)
+4. If decision is `defer-extract`: user must confirm extraction plan in chat
+
+## Emergency bypass (temporary only)
+
+- `SMOKE_TEST_IGNORE=true` on a single deploy
+- `workflow_dispatch` deployment smoke against a known-good URL
+- Skip Vercel Deployment Check with **human** approval
+
+Never treat emergency bypass as permission to land a permanent customer patch for `@se-studio/*` behaviour.

package/references/agent-session/smoke-deploy-failure-playbook.md

@@ -0,0 +1,80 @@
+# Smoke / deploy failure playbook
+
+When **local smoke**, **`smoke-test:live`**, or **Vercel Deployment Checks** fail, follow this sequence. Do **not** patch customer origin/URL logic to satisfy `@se-studio/site-check` assertions.
+
+Full refusal rules: [`refuse-customer-patches.md`](./refuse-customer-patches.md).
+
+## 1. Classify the failure
+
+Read the failing step and package:
+
+| Failure mentions | Likely owner |
+|------------------|--------------|
+| `discovery`, `llms.txt`, `markdown-index.txt`, `urlOrigin`, canonical origin | `@se-studio/site-check` |
+| `article link integrity`, `cmsIntegrity` | `@se-studio/site-check` + site `routing` config (customer OK) or `contentful-rest-api` (core) |
+| `route-build-policy`, `mustBeSsgOrStatic`, `ƒ` on CMS route | Site introduced dynamic APIs — fix site routing/layout **or** core if shared helper caused it |
+| HTML 404/500 on a **curated** smoke path | Site content/routing or CMS — usually **customer** |
+| Lockfile / install on Vercel | Customer lockfile sync — see `lockfile-sync` reference, not site-check |
+
+## 2. If `@se-studio/*` behaviour is wrong → core-first
+
+1. Set manifest `mode: core-first` (or stop and ask user to switch).
+2. Fix in `packages/<pkg>/`, add **changeset**, run package tests.
+3. Push `dev` → wait for CI npm publish.
+4. Add/update `work/tracker.yaml` **rollout** for customer bumps.
+5. Set customer manifest `blocked_on: "@se-studio/<pkg>@<version>"` until npm confirms.
+
+**Customer repo during wait:** only dependency bump via `pnpm update` — no `baseUrl` / origin / assertion hacks.
+
+## 3. If site content/routing is wrong → site-first
+
+Examples: wrong slug in `smoke.cases.json`, page unpublished, new article type needs a case.
+
+1. Confirm placement `customer`.
+2. Refresh cases from production sitemap (`se-marketing-sites-smoke-test-setup` skill).
+3. Run `pnpm smoke-test:run` locally; `pnpm smoke-test:preview` against develop preview if needed.
+
+## 4. Discovery canonical origin (known anti-pattern)
+
+**Symptom:** Deploy smoke hits `https://<project>-<hash>.vercel.app` but `llms.txt` / `markdown-index.txt` list `https://www.example.com/...` links. Smoke fails origin check.
+
+**Wrong fix (refuse):**
+
+- `getRequestBaseUrl()` from request headers in `server-config` or discovery routes
+- Rewriting discovery output to match deployment host permanently
+
+**Right fix:**
+
+1. Core: `@se-studio/site-check@2.9.4+` with `discovery.urlOrigin: auto` (default in smoke runner).
+2. Customer: `pnpm update @se-studio/site-check@2.9.4 -r`, keep canonical `baseUrl` in app config.
+3. Tracker rollout: `site-check-discovery-canonical` in `work/tracker.yaml`.
+
+## 5. Emergency unblock (human or agent with explicit approval)
+
+| Action | Use when |
+|--------|----------|
+| `workflow_dispatch` deployment smoke | Re-test after core fix + customer bump |
+| `SMOKE_TEST_IGNORE=true` | One-off deploy; document in manifest notes |
+| Human approves blocked Deployment Check | Production promotion already reviewed |
+
+Record what was bypassed and the real fix still required (core PR / npm bump).
+
+## 6. Validate before customer push
+
+| Check | Command |
+|-------|---------|
+| Local HTTP smoke | `pnpm smoke-test:run` |
+| Preview smoke | `pnpm smoke-test:preview` (develop URL + bypass token) |
+| After core bump | `pnpm update @se-studio/site-check@<version> -r` then re-run smoke |
+| Route policy | `pnpm validate:routes` when Contentful creds available in CI |
+
+Deployment checks stay **HTTP-only** — never enable `cmsIntegrity` on Vercel live smoke.
+
+## 7. Handoff
+
+Include in manifest / handoff:
+
+- Root cause (core vs customer)
+- Published package versions required
+- Tracker rollout id
+- Whether any emergency bypass was used

package/references/lockfile-sync/README.md

@@ -48,7 +48,7 @@ Apply the full stack when touching deps or CI in each repo:
 | brightline-sites | yes | yes | yes | yes |
 | pedestal-sites | — | partial | — | no |
 | om1-website | — | — | — | — |
-| se-website-2026 | — | — | — | — |
+| se-website-2026 | yes | yes | yes | yes |
 | pointme | — | — | — | — |
 
 Update this table as repos adopt the pattern.

package/skills/se-marketing-sites-smoke-test-setup/SKILL.md

@@ -377,6 +377,24 @@ Commit `route-build-policy.json` beside `smoke.cases.json`. Start from `@se-stud
 
 **HubSpot bootstrap:** use `createHubSpotBootstrapScript()` with no args in root layout — not `headers()` + middleware pathname.
 
+## Deploy / live smoke failure playbook
+
+When **`pnpm smoke-test:live`**, Vercel Deployment Checks, or preview smoke fail after a dependency bump, **do not** patch customer `baseUrl`/origin logic to satisfy `@se-studio/site-check`.
+
+**Playbook:** [`packages/skills/references/agent-session/smoke-deploy-failure-playbook.md`](../../references/agent-session/smoke-deploy-failure-playbook.md)
+
+**Refusal rules:** [`packages/skills/references/agent-session/refuse-customer-patches.md`](../../references/agent-session/refuse-customer-patches.md) (agent-session Step 3b)
+
+Quick sequence:
+
+1. **Classify** — discovery/origin → `site-check`; broken slug → customer `smoke.cases.json`; new `ƒ` route → fix dynamic APIs.
+2. **Core-first** if package behaviour is wrong — changeset, push `dev`, tracker rollout, customer `blocked_on` until npm.
+3. **Customer-only** if curating URLs — refresh from sitemap; one case per **enabled** article-type segment.
+4. **Discovery canonical origin** — bump `site-check@2.9.4+`; never add `getRequestBaseUrl()` (tracker rollout `site-check-discovery-canonical`).
+5. **Emergency** — `SMOKE_TEST_IGNORE` or `workflow_dispatch` smoke; not a permanent site patch.
+
+Record `placement.decision` in manifest before smoke/server-config commits aimed at unblocking deploy.
+
 ## Reference
 
 - HTTP + integrity example: `apps/example-empty/smoke.cases.json` and `scripts/smoke-test-run.ts` (monorepo).

package/skills/site-workflows-agent-session/SKILL.md

@@ -78,6 +78,16 @@ If the user works only in a customer repo with no core checkout, still create/up
 
 **One feature = one manifest.** Do not append unrelated work to an existing manifest.
 
+### Cross-site tracker (`work/tracker.yaml`)
+
+For work that spans repos (core npm rollouts, deployment gates, “bump on all sites”):
+
+1. Add or update a `rollouts` entry in `work/tracker.yaml` when a `@se-studio/*` release needs customer adoption
+2. Add `attention` items for human-only gates (blocked Vercel deploy, hosted MCP smoke, merge decisions)
+3. Run `pnpm work:tracker` from se-core-product to refresh `work/TRACKER.md`
+
+Humans glance at **`work/TRACKER.md`** for the dashboard; agents edit `tracker.yaml` + manifests.
+
 ---
 
 ## Step 3 — Placement checklist (before non-trivial code)
@@ -105,6 +115,25 @@ Run before implementing anything beyond a one-line fix. Record results in manife
 
 **Core-first guard:** If checklist says `customer`, implement in customer repo (read-only probe in core example apps only if useful).
 
+### Step 3b — Refuse customer patches (mandatory)
+
+After the placement checklist, run the **refusal table** when the task involves deploy smoke, `smoke.cases.json`, discovery routes, `server-config`, or “fix site-check / unblock Vercel.”
+
+**Reference:** [`packages/skills/references/agent-session/refuse-customer-patches.md`](../../references/agent-session/refuse-customer-patches.md)
+
+| If the fix would… | Agent must |
+|-------------------|------------|
+| Patch `@se-studio/*` behaviour in the customer repo | **Refuse** — core-first + changeset |
+| Add `getRequestBaseUrl` or per-request origin for discovery smoke | **Refuse** — bump `@se-studio/site-check@2.9.4+` (`discovery.urlOrigin: auto`) |
+| Change `route-build-policy.json` only to hide a new `ƒ` CMS route | **Refuse** — fix dynamic usage (Biome / layout) |
+| Add curated URLs or site-only probe cases | **Allow** — placement `customer`; follow smoke-test skill |
+
+**Deploy / live smoke failed?** Follow [`smoke-deploy-failure-playbook.md`](../../references/agent-session/smoke-deploy-failure-playbook.md) — classify failure → core vs customer → `blocked_on` if waiting on npm. Emergency: `SMOKE_TEST_IGNORE` or human Deployment Check approval — **not** permanent site hacks.
+
+**Manifest gate:** Before committing customer changes to smoke config, discovery routes, or `server-config` for deploy-smoke goals, record `placement.decision` in `work/active/<feature>.yaml`. If `core`, do not commit customer workaround.
+
+**`defer-extract`:** Only when the user explicitly approves in chat. Set `extract_to_core: pending` + rationale; add tracker rollout if multi-site.
+
 ---
 
 ## Step 4 — Git isolation