@mutmutco/pi-plugin 4.6.2 → 4.6.4

package/skills/org-guide/references/work-and-releases.md

@@ -35,6 +35,11 @@ MMI_ACTOR=app mmi-cli devops read pr list --repo <owner/repo> --head <branch> --
 ```
 For run logs, never native `gh run view --log`/`--log-failed`: use
 `MMI_ACTOR=app mmi-cli devops read run log <runId> --repo <owner/repo> [--failed | --job <name>] [--tail N]`.
+A `https://github.com/<owner>/<repo>/actions/runs/<id>` web URL is auth-gated: an unauthenticated page fetch
+(`fetch_content`) returns HTTP 404 (GitHub answers 404, not 403, for private repos the extractor cannot see), so
+treat a 404 from `github.com` as missing authentication rather than a moved page and read the run with
+`MMI_ACTOR=app mmi-cli devops read run view|log <id> --repo <owner/repo>` or
+`MMI_ACTOR=app mmi-cli devops api get repos/<owner>/<repo>/actions/runs/<id>/jobs` (#9480).
 A refused command writes no output, so a `> file` redirect leaves it empty or missing: read the
 refusal, then rerun the typed form.
 
@@ -59,303 +64,7 @@ Never defer a live check waiting for real data (owner ruling 2026-10-27T20:04Z,
 state it verifies with the module's dev/admin tools (MDT verbs, admin endpoints, module CLI,
 synthetic accounts); if a needed verb is missing, add it in the same lane, then verify now.
 
-Owner ruling 2026-10-25 (#8814, #8816, MM-Work#7629; `docs/decisions/2026-10-06-browser-checks-nightly.md`):
-the required `gate` holds fast deterministic checks only; UI/design uses `@mutmutco/mmwork-ds`
-(`mmwork-check-ui`) and the mandatory Impeccable skill/toolkit. Inspect all applicable toolkit
-capabilities for every design task. Work on the live app; use our own MM Artifacts A/B canvas only
-for owner design choices, with live kit pieces and recorded choice ID / owner-decision reference.
-A canvas is for how something looks or works on screen only (#8986, relay wording): approvals for
-keys, releases, deletions, data access or tooling never go on a canvas; send them to the
-orchestrator, who asks the owner in plain words.
-Functional browser journeys remain opt-in `workflow_dispatch`-only, never design checks or gates.
-
-## The MM Open Design System Bible (#8837, #8839)
-
-Every agent doing UI, design, document or MM Artifact work reads this first: Part 1 builds the
-system, Part 2 improves it, Part 3 governs A/B choosing, Part 4 gates kit changes on visual A/B.
-Handoff and workaround notes cite this section by path and add only the task's own deviation,
-failure and action, never a restatement; new owner rulings are still recorded verbatim.
-
-### Part 1 — The five pillars of the MM Open Design System
-
-Owner ruling 2026-10-25 (#8837, MM-Work#7668): the stage skill is retired completely. UI and
-design work follows one harmonized **Front-Loaded Impeccable v4.7.0 + MM Artifacts + Live Docs
-(`Canlı belgeler`) + Atomic Design Kit (`@mutmutco/mmwork-ds`)** workflow:
-
-- **Front-load Impeccable** before any UI or MM Artifact authoring: `impeccable context --target <path>`,
-  `DESIGN.md` plus its `design.json` sidecar in `.impeccable`, shared `.impeccable/config.json`
-  (`hook.enabled: true`), `reference/craft-floor.md` + `reference/operate.md`, and
-  `impeccable detect --json <target>`.
-- **MM Artifacts** (local/canvas packs in the `mm-artifact` v3 format) use one command,
-  `node artifacts/review/review.mjs <folder>`. It runs `check.mjs`, `check-ui.mjs` and
-  `geometry.mjs`, pre-renders the board in `node:vm` via `ReactDOMServer.renderToStaticMarkup` into
-  `#root` and runs `impeccable detect --json` on that SSR-rendered HTML. Interactive owner A/B
-  reviews use the live loopback HTTP review server (`http://127.0.0.1:<port>/`), where the owner's
-  `Send answers` posts back to `POST /answers`; a seat must not open the owner's browser. An A/B is
-  shown as the live canvas link, never as prose (#8987, relay wording). Once the canvas passes review,
-  send the orchestrator only the review URL and issue number, and keep the server running until the
-  owner answers. A kept-alive canvas review server must stay light (no dev/watch build pinning
-  gigabytes); a seat whose canvas needs a heavy local server flags that to the orchestrator instead
-  of holding the RAM silently, and stops it as soon as the owner has answered. The orchestrator opens
-  it on the owner's screen. `--standalone [<out.html>]` is only
-  for offline HTML previews/exports and SSR pre-render verification, never for an interactive owner
-  decision.
-  **Headless seat rule:** `--open` is review.mjs-only; never pass `--open` to `vite`, and never use it from a seat to open the owner's browser for an A/B review.
-  Vite parses its value as a URL path, so `vite --open false` opens the owner's real browser at `/false`;
-  run dev/preview servers with `BROWSER=none` and no `--open` flag.
-- **Live Docs** (`Canlı belgeler` viewer) carry the living references, including the live
-  design-system artifact `3a5c79df-5274-40ad-a1b5-a75e67a74dac`.
-- **Atomic Design Kit** (`@mutmutco/mmwork-ds`): kit pieces and tokens only, checked with `mmwork-check-ui`.
-
-How the five pillars fit together (owner, 2026-10-25):
-
-| Pillar | What it is | Claude / industry analogy | Where it lives |
-|---|---|---|---|
-| **1. MM Artifacts (`mm-artifact`)** | The HTML artifact file format (`type: 'document' \| 'canvas' \| 'design-system'`). By default a single self-contained HTML artifact; a multi-board Canvas only when comparing A/B options or viewport sizes side by side. | Claude Artifacts (the HTML artifact itself) | Local `.html` / `artifact.json` during agent dev (opened straight in the browser); stored in Live Docs when shared or created by Junior. |
-| **2. Design System Artifacts (`type: 'design-system'`)** | MM Artifacts stored in Live Docs that define a complete visual system (tokens, CSS, components, `DESIGN.md`). Every MM Artifact binds to one (`kit: { id, version }`). Includes (a) the MM-Work Atomic Design System (`3a5c79df`, MM-Work app and modules), (b) the Document/Editorial Design System (reports, checklists, decks, client documents), and future brand/client systems. | Claude Design Systems / theme packs an artifact pulls from on creation | Hosted in Live Docs (`Canlı belgeler`). Only the MM-Work app design system is also exported to npm (`@mutmutco/mmwork-ds`). |
-| **3. Live Docs (`Canlı belgeler`)** | The viewer, library, commenter and A/B picker inside the MM-Work app (`/documents/:id`), where people, Junior and agents view, comment on, version and share MM Artifacts. | Claude's Artifact viewer / workspace panel | Built into MM-Work (`web/src/documents/`, `src/documents.ts`). |
-| **4. Open Design Kit (`@mutmutco/mmwork-ds`)** | The npm package generated from `packages/mmwork-ds/source/` (the source of the MM-Work Atomic Design System), so MM-Work, the 10 suite modules and local app-UI MM Artifacts render real Atoms, Molecules, Organisms, Templates and Pages. | Published React/CSS component kit | `packages/mmwork-ds/source/` → `@mutmutco/mmwork-ds`, synced to Live Docs (`3a5c79df`) and all 10 module roots. |
-| **5. Impeccable (`v4.7.0`)** | The front-loaded design craft and quality engine (`impeccable context`, `craft-floor`, 15 playbooks such as `distill`, `typeset`, `layout`, `colorize`, `clarify`, `polish`, plus `impeccable detect --json` and `DESIGN.md`). Runs in front of every UI or MM Artifact creation so output is readable, well typeset, purposefully coloured and never AI slop. | Design director + mechanical UI linter | `.agents/skills/impeccable` + root `DESIGN.md` and the `design.json` sidecar in `.impeccable`. |
-
-Four owner decisions (2026-10-25T15:35:52Z):
-
-1. **Doc vs. app kit — add a Document Design System too.** Keep the MM-Work Atomic Design System (`3a5c79df-5274-40ad-a1b5-a75e67a74dac`) for MM-Work and module app UI (and as the fallback for now), and add a dedicated Document/Editorial Design System Artifact in Live Docs for reports, checklists, decks and client documents made by Junior or agents.
-2. **Where to save — local HTML for dev, Live Docs for shared.** Coding agents build local `.html` MM Artifacts for fast iteration. For interactive owner A/B reviews, serve the canvas on the live loopback HTTP review server (`http://127.0.0.1:<port>/` with `Send answers`) without opening the owner's browser; relay the URL and issue number to the orchestrator and keep the server running until the owner answers (#8987, relay wording). A kept-alive canvas review server must stay light (no dev/watch build pinning gigabytes); a seat whose canvas needs a heavy local server flags that to the orchestrator instead of holding the RAM silently, and stops it as soon as the owner has answered. Use `node artifacts/review/review.mjs <folder> --standalone [<out.html>]` for offline HTML previews/exports or SSR pre-render verification. Publish to Live Docs only for a shared deliverable, an A/B decision canvas or a Design System. Junior inside MM-Work saves directly to Live Docs.
-3. **Artifact shape — single HTML by default, Canvas for A/B.** A single self-contained HTML view for documents, checklists and single-screen work; a multi-board spatial Canvas only for A/B choices or `1440`/`1024`/`390` side-by-side comparisons.
-4. **Kit binding — Live Docs hosts kits; npm only for MM-Work.** Every Design System Artifact in Live Docs stores its tokens/CSS/components and `DESIGN.md` so any HTML artifact can bind to it (`kit: { id, version }`); only the MM-Work app design system is also exported as `@mutmutco/mmwork-ds`, because the MM-Work app and the 10 suite modules compile against it.
-
-Impeccable **v4.7.0 / engine v0.1.16** details:
-
-- Impeccable is invoked as the installed script at `~/.agents/skills/impeccable/scripts/impeccable` or
-  bare `impeccable` on `PATH` — no Impeccable CLI is published on npm, so never run
-  `npx @impeccable-style/cli ...` (it 404s) or chain `npx` guesses into git/bootstrap commands (#8885).
-  Refresh the local kit cache through MMI-Hub `scripts/kit-adopt.mjs`'s `refreshKitCache({ mmWorkRoot, cacheRoot })`
-  (#9271, #9279). It runs `node "<absolute-MM-Work-root>/scripts/sync-design-system.mjs" "<absolute-MM-Work-root>/packages/mmwork-ds/source" --out "<staging-dir>"`
-  (the source argument is required, #8887) into a staging dir inside the cache root, then publishes that output to
-  `<cache-dir>/<version>/`, `<cache-dir>/latest/` and `version.json`, which is what `scripts/kit-adopt.mjs --local-dir`
-  reads. Run the sync yourself only into such a staging dir: `--out` alone writes the generated files flat and writes no
-  `package.json`, so a bare `--out "<cache-dir>"` fills a cache `--local-dir` cannot resolve. The cache dir is the machine
-  cache `~/.jerv/cache/mmwork-ds`. Never run the two-argument form: without `--out`
-  the sync writes the nine generated kit files and `sync.json` into the MM-Work working tree, where they are
-  post-merge bot output, MM-Work's lane guard refuses a commit touching them, and a lane that already ran it cleans
-  up with `git checkout -- packages/mmwork-ds`. Never commit those files (#9271). Resolve and verify the checkout as described under
-  [shared support-script invocation](#shared-support-script-invocation). A local `npm ci` against `npm.pkg.github.com` that returns
-  `E401` needs the GitHub Packages credential, never the npm one: the Jerv vault key `GH_PACKAGES_READ_TOKEN`, used keyless
-  (`jerv-cli vault use GH_PACKAGES_READ_TOKEN -- sh -c 'NODE_AUTH_TOKEN="$GH_PACKAGES_READ_TOKEN" npm ci --prefix module'`),
-  or your own `gh` login when it carries `read:packages` (`NODE_AUTH_TOKEN=$(gh auth token) npm ci --prefix module`); the
-  org `npm/NPM_TOKEN` belongs to `registry.npmjs.org` and returns `E401` here. Or adopt credential-free
-  with `mmi-cli devops packages adopt-export` (`docs/Guides/package-adopt-export.md`, #8886). To probe a kit
-  version, read the pin from the consumer's module/`package.json` (or `node_modules/@mutmutco/mmwork-ds`); a bare
-  `npm view @mutmutco/...` asks the public registry only and 404s, because the scope lives on GitHub Packages (#9238).
-  A registry read needs the registry flag and a token: in a consumer whose `.npmrc` maps the scope,
-  `NODE_AUTH_TOKEN=$(gh auth token) npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com`;
-  from a root without that line, pass the token directly —
-  `npm view @mutmutco/mmwork-ds@<v> version --registry https://npm.pkg.github.com --//npm.pkg.github.com/:_authToken=$(gh auth token)`.
-  To see **which** kit versions are actually published, run MMI-Hub's
-  `node scripts/kit-adopt.mjs --list-versions [--limit 5] [--json]` (#9426) instead of deriving it: it reads GitHub
-  Packages `/orgs/mutmutco/packages/npm/mmwork-ds/versions` (newest first, falling back to `npm view` against
-  `https://npm.pkg.github.com` with `GH_PACKAGES_READ_TOKEN`/`NODE_AUTH_TOKEN`), reports the local cache's latest
-  version, and never hits the `registry.npmjs.org` 404 of a bare `npm view @mutmutco/mmwork-ds` (#9264). That is the supported listing read:
-  `mmi-cli devops packages` covers consumer adoption (`adopt-export`) only, so it never names a published
-  version — never carry the packages API as a stopgap.
-- Boot once: `impeccable context --target <path>`; `init` captures PRODUCT.md, `document` maintains
-  `DESIGN.md` and its `design.json` sidecar, `impeccable doctor --json` reports drift, and `extract`
-  identifies reusable candidates (kit additions still need the Design Lead). Read
-  `reference/craft-floor.md` before UI edits and `reference/operate.md` for app UI.
-- `impeccable hooks on` enables shared `.impeccable/config.json`; local overrides/consent belong in
-  ignored `.impeccable/config.local.json`. Tier 1 scans mechanical problems per edit; Tier 2 deep-scans
-  at turn-end `Stop` on supported hosts. Verify `hooks status` and host support, not config alone.
-  If automatic hooks are unavailable, run `impeccable detect --json <target>` manually on markup
-  files/directories (not CSS-only): **0 clean / 2 findings**. Unavailable or broken scans are not passes.
-- Dual-subagent `critique` keeps design assessment independent from detector evidence and persists via
-  `critique-storage`; disclose degraded runs. `audit` scores accessibility, performance, theming,
-  responsive design and implementation integrity 0–4 each (**20 points**). These evaluations are
-  agent playbooks, not standalone engine CLI verbs; still inspect the live result.
-- Pick relevant playbooks: `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard`, `layout`,
-  `typeset`, `colorize`, `animate`, `delight`, `overdrive`, `clarify`, `adapt`, `optimize` (15 names in
-  v4.7.0, despite the requested “14”). Do not apply conflicting playbooks blindly.
-- Iterate with `live` / `generate` (`live-generate`, `live-poll`, `live-server`); `serve-question`
-  supports choices, while owner A/B decisions use the MM Artifacts canvas.
-  Stop temporary servers. Check installed versions and approved upstream updates via the owning
-  installer; do not modify shared skills from a module task. Record command + exit + findings,
-  kit version and available checks separately from contract identity; reports are not conformance.
-
-Craft essentials every agent applies (owner, 2026-10-25, #8839):
-
-- **Sleek translucent glass cards and zero GPU usage — never color-washed
-  (`2026-10-25T16:21:19.344Z`).** Cards use sleek, modern translucent glass material (neutral
-  translucent surface with a crisp glass rim, `--card-tint-dark: 0%`, `--card-tint-light: 0%`)
-  rather than color-washed card fills in any theme, and zero GPU-compositing blur or shadow
-  (`--card-blur: none`, `--card-blur-frost: none`, `--frost-see-blur: 0px`, `--glass-blur: none`,
-  `--card-shadow-dark: none`; never `backdrop-filter: blur(...)`). Module tones (`blue`, `coral`,
-  `teal`, `purple`, `terracotta`, `green`, `pink`, `lime`, `cyan`, `magenta`, `fuchsia`)
-  belong on `Badge`, `Mark`, `Checkbox` (`lead`), and card `icon`/`mark` accents (`edge="bite"`).
-- **Front-loaded Impeccable v4.7.0, in front of creation.** Run `impeccable context --target <path>`,
-  read `DESIGN.md` and `reference/craft-floor.md`, choose the surface mode (`Operate`, `Read`,
-  `Persuade` or `Experience`) and load the matching playbooks (`shape`, `distill`, `typeset`,
-  `layout`, `colorize`, `clarify`, `polish`, `harden`, `adapt`) before writing markup.
-- **Restraint and hierarchy.** Group related items into clean section `Card`s (`heading: 2` under
-  the page `<h1>`), keep main-column rows concise (`Cluster` with `fill` = `Checkbox` plus one
-  trailing action), and put multi-line inspector detail in the right-hand `HelperCard` as `Stack` +
-  `Text` — never `DataList`, which clips multi-line prose. No walls of text.
-- **Verify the SSR pre-rendered HTML.** `impeccable detect --json` is blind on an unrendered
-  `<div id="root"></div>` file, so verify the output of `review.mjs <folder> --standalone --open`,
-  which pre-renders the board into `#root` first. An empty `#root`, missing fonts or an unrendered
-  detector run is a failed check, not a pass. For one page-spec module, run
-  `node scripts/design-pack-render.mjs --page-spec <spec.mjs>` (it SSR-renders `renderPage(ctx)` per
-  theme mode and runs `impeccable detect --json` on the HTML), or `node artifacts/review/review.mjs
-  <folder> --standalone` for a pack; never hand-roll an inline `node -e` SSR script, which evaluates
-  as CommonJS and fails on the spec's ESM `import` lines (#8876).
-
-### Shared support-script invocation
-
-Resolve shared support tools from their **known canonical checkout**, not the caller's module/worktree
-layout (#8890). Never guess `../../MMI-Hub/scripts/kit-adopt.mjs`: that can resolve to the
-`mmi-worktrees/MMI-Hub` container, not a checkout, or to a sibling branch without the script.
-
-1. Start with a known absolute MMI-Hub checkout/worktree path supplied by repository or host metadata.
-   If only a Hub task worktree is known, use `git -C "<known-Hub-worktree>" rev-parse --path-format=absolute --git-common-dir`
-   and `git -C "<known-Hub-worktree>" worktree list --porcelain` to identify its canonical/main checkout.
-   Git metadata is repository-specific: a module's common directory cannot locate MMI-Hub. If no Hub
-   checkout is known, ask for it; do not scan drive roots or traverse arbitrary parents.
-2. Verify the selected checkout's identity with `git -C "<absolute-Hub-root>" remote get-url origin`
-   (must identify `mutmutco/MMI-Hub`) and verify `"<absolute-Hub-root>/scripts/kit-adopt.mjs"` exists as
-   a file before invocation. If missing, stop and resolve the correct checkout/version; do not retry
-   sibling guesses or create a replacement script.
-3. Resolve each target/source independently to its intended absolute path. Invoke Node with separate,
-   quoted arguments, for example:
-   `node "<absolute-Hub-root>/scripts/kit-adopt.mjs" --local-dir "<absolute-module-root>" --version <kit-version>`.
-   For cache refresh, verify `<absolute-MM-Work-root>/scripts/sync-design-system.mjs`, then
-   pass the absolute script path, the absolute `packages/mmwork-ds/source` path and `--out "<absolute-cache-dir>"`
-   as shown above: the generated kit files and `sync.json` land in the cache, never in the MM-Work checkout (#9271).
-   These are path patterns, not literal host paths; keep machine-specific roots out of bundled docs.
-
-Verify paths before chaining unrelated operations such as a board claim. Path resolution grants no
-new authority: use only the tool mode and target already authorized; never replay a successful claim
-just because a later script failed to load.
-
-### Part 2 — The System-First Autolearn Doctrine (never work around a broken tool in `tmp/`)
-
-Owner ruling 2026-10-25T15:41:41.360Z (#8839): agents learn from their work, mistakes and
-discoveries with the MM open design system and improve the system wherever they can, instead of only
-fixing the current situation. Never patch the moment in `tmp/` and leave the shared system broken.
-If creating, bundling, rendering, checking or opening an MM Artifact or a design-kit change needs a
-custom script in `tmp/`, a patch around a bundler regex, manually inlined fonts, or locally overridden
-broken tokens, that is a **system defect, not a local task**.
-
-The immediate three-step system upgrade reflex:
-
-1. **Step A — fix the shared system at its source.** File or claim an issue, or message the owning
-   suite seat (Design Lead, MM-Work, Jerv-JervCode, MMI-Hub, Jerv-Hub), so the shipped CLI, bundler,
-   token, component or skill is fixed in its repository and no agent ever needs the workaround again.
-   A temporary workaround may unblock the task only when it is named as such and linked to that issue.
-2. **Step B — record it in the autolearn queue** (`jerv_learning_note` in JervCode, or
-   `mmi-cli learning skill-lesson --skill <name> --title <summary> --body-file <path>`): the exact
-   friction and its root cause, so autolearn turns it into a durable doctrine, code or skill fix.
-3. **Step C — record it in Hindsight memory** (`hindsight_ingest_document`): the root cause and the
-   permanent system fix, so every later session recalls it automatically.
-
-Autolearn watches design and artifact work for these signals and escalates each into a shared
-toolchain, kit or skill improvement: ad-hoc build/render/verify scripts under `tmp/`, empty `#root`
-renders, missing fonts, unrendered `impeccable detect` runs, geometry or layout regressions,
-graywashed or untinted surfaces, verbose walls of text, and skipped front-loaded `impeccable context`
-or playbook passes. Reflect after each design task: what would have made this easier for the next
-agent, and is that improvement filed?
-
-### Part 3 — A/B Choosing Architecture & Viewer Rules (owner ruling 2026-10-25T15:57:26.199Z, #8841)
-
-Settled owner ruling: present clear, distinct choices in the existing MM Artifact viewer, not a
-"shell over a shell". These are authoring and viewer requirements, not proof of installed capabilities.
-
-**Canvases carry design choices only (#8986, relay wording).** An A/B canvas asks how something
-looks or works on screen. Approvals for keys, releases, deletions, data access or tooling never go on
-a canvas: send them to the orchestrator, who asks the owner in plain words.
-
-1. **No "shell over a shell" — designer agents build only the alternatives, never their own A/B switcher.**
-   The outer MM Artifact viewer (the local review shell and `CanvasStage` / `CompareView` in Live Docs)
-   already IS the A/B selector shell: it renders the question prompt, Option A / Option B / Neither
-   buttons, notes and board switcher. A `designer` subagent must **NEVER** draw an A/B picker,
-   question header, option cards or a gallery of tiny `ThemePreview` thumbnails inside a board.
-   **One A/B decision = one page with two full-resolution live HTML boards:**
-   - `board-a`: the actual full-size (`1440x900`) live MM-Work screen rendered in **Option A**
-     (for example, Linear Dark).
-   - `board-b`: the exact same full-size (`1440x900`) live MM-Work screen rendered in **Option B**
-     (for example, Apple Black).
-   Never pack multiple themes or multiple options onto a single board.
-2. **Compare the live HTML artifacts directly — never screenshots or low-res thumbnails.**
-   Both options are live, vector-sharp HTML/CSS/React artifacts rendered from `@mutmutco/mmwork-ds`,
-   never raster PNG screenshots or shrunken preview cards. The A/B viewer must let the owner inspect
-   Option A and Option B side-by-side or toggle 1:1 at full crisp resolution, so subtle palette,
-   contrast and typography differences (such as Linear Dark vs. Apple Black) are immediately clear.
-3. **Content-only zoom — zoom the artifact content, never the outer A/B shell.**
-   In the local review viewer and Live Docs (`CanvasStage` / `BoardBridge`), `wheel` events
-   (including `ctrlKey` / `metaKey` pinch-zoom) and keyboard zoom (`Ctrl/Cmd + +/-/0`) on both the
-   outer review shell and inside board iframes (forwarded via `postMessage`) must call
-   `preventDefault()` and zoom **only the artifact canvas/board viewport**. `Ctrl + Mousewheel` and
-   viewer zoom controls must keep the outer A/B selector shell, question bar and controls at a fixed
-   1:1 UI size.
-
-4. **A recorded owner answer is decided state — read it back, never re-ask (owner ruling, #9259).**
-   An answer the owner already gave on an A/B canvas is durable decided state, not a pending question.
-   Before re-presenting or re-asking any A/B choice, read the recorded answer — `answers.json` in the
-   canvas folder plus the canvas choice ID Part 4 Stage 2 says to record — and when a canvas is reopened,
-   rebuilt or replaced, carry that pick forward and show the board as already answered. Never tell the
-   owner he has not picked while a recorded pick exists: a decided board reads as decided, naming where
-   and when it was chosen, and the work proceeds instead of stalling behind a closed question.
-
-### Part 4 — Visual A/B Choice via Designer Subagent Before Kit Implementation — Never Prose Specs (owner ruling 2026-10-25T16:29:46.339Z, #8844, #8846, #8848)
-
-Settled owner ruling (verbatim): "You should use a designer to create a couple card designs with my
-specifications and then let me choose then build the complete spec into the design system, replacing
-any other card available atomically. That's the proper way to do it. Learn from this mistake of yours,
-requests like this should follow this structure, not prose guide."
-
-1. **Never reply with a prose specification in chat or jump straight to kit implementation.**
-   When the owner asks to "design the spec for X and add it to the design system" (for example, The One
-   Card), writing a markdown or prose spec in chat violates Principle 7 ("Choices for Jervaise go only
-   on the A/B canvas"). Building one guessed design straight into the kit skips the owner's choice.
-2. **Always follow the visual spec pipeline:**
-   - **Phase 0 — Inspiration via front-loaded Impeccable v4.7.0 and 21st.dev MCP (`https://21st.dev/api/mcp`) only (owner ruling 2026-10-25T21:37:00+03:00, #8854; superseding #8848).**
-     Before building visual A/B boards, use front-loaded **Impeccable v4.7.0** alongside **21st.dev MCP**
-     (`https://21st.dev/api/mcp`; verbatim owner ruling: `"we don't need the mcp better design yet,
-     impeccable and 21st is enough"`, dropping Better Design MCP) to study high-craft reference patterns,
-     layout proportions, and interaction details. Always translate inspired patterns into zero-GPU
-     `@mutmutco/mmwork-ds` tokens (`--card-blur: none`, `--card-tint-dark: 0%`, `--card-tint-light: 0%`,
-     sleek translucent glass cards) and Atomic Design layers; never copy raw third-party CSS/HTML or
-     GPU-heavy effects. `MM-Inspo` is strictly a customer/tenant module inside the MM-Work suite, never
-     an internal tool for designing the MM-Work app or its design system.
-   - **Stage 1 — a designer subagent builds visual A/B alternatives on an MM Artifact canvas.**
-     Dispatch a `designer` subagent with front-loaded Impeccable (`impeccable context`, `craft-floor`,
-     `distill`, `typeset`, `layout`, `colorize`, `polish`) to create 2–3 genuinely distinct visual
-     designs that honor every constraint in the owner's brief: Option A, Option B and optionally
-     Option C, each its own full-resolution `1440x900` live HTML board in one MM Artifact A/B canvas
-     (Part 3 rules: content-only `Ctrl + Mousewheel` zoom, 1:1 or side-by-side live comparison). Serve
-     the verified canvas on the live loopback HTTP review server without opening a browser from the
-     seat, so the owner's `Send answers` posts straight back to `POST /answers`. Once review passes,
-     send the orchestrator only the review URL and issue number, and keep the server running through
-     Stage 2; the orchestrator opens it on the owner's screen (#8987, relay wording). Never open a
-     `--standalone` `file://` export (`Download answers.json`) for an
-     interactive owner A/B decision: `--standalone [<out.html>]` is only for offline previews/exports
-     and SSR detector checks. Spawn a dedicated, fresh
-     `designer` subagent for each distinct design task (item 3); never reuse a busy designer seat.
-   - **Stage 2 — the owner chooses visually on the A/B canvas.** Wait while the owner inspects the
-     live HTML alternatives, zooms into details and picks the preferred design or asks for
-     adjustments, then presses `Send answers` on the live review server page; `review.mjs` writes
-     `answers.json` into the canvas folder and exits. Record the canvas choice ID and the
-     owner-decision reference.
-   - **Stage 3 — atomic replacement in the kit source.** Only AFTER the owner picks on the A/B canvas,
-     build the chosen design into the source folder of packages/mmwork-ds in mutmutco/MM-Work,
-     **atomically replacing** every other legacy or competing variant of that piece across the design
-     system, publish it to `Canlı belgeler` / MM-Work, and propagate it to all 10 suite modules.
-3. **One dedicated `designer` subagent per distinct design task — never overload a designer seat
-   (owner ruling 2026-10-25T16:33:00Z, #8846).**
-   Settled owner ruling (verbatim): "The lead designer sent the card building to the same designer
-   agent, overloading it. I don't think it was a wise idea. Please learn from this."
-   Spawn a separate, fresh `designer` subagent in its own isolated lane for each distinct design task
-   or visual A/B canvas (for example, a theme A/B exploration vs. a unified Card spec A/B). Never steer
-   or queue a second unrelated design task onto an active `designer` seat: overloading one
-   `designer` subagent serializes work that should run in parallel, bloats its context window, and
-   degrades craft quality.
+UI, design, document and MM Artifact work follows the [design topic](design.md): the required `gate` holds fast deterministic checks only, and owner A/B choices go on an MM Artifacts canvas, never as prose.
 
 ## Documentation preflight
 

package/skills/rcand/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rcand
-description: Promote development to a release candidate.
+description: Promote development to a release candidate on rc. Use on a full-track repo before release, not for a direct-track repo or an urgent fix (hotfix).
 ---
 
 **Host-native invocation:** Claude `/mmi:rcand` · Codex `$mmi:rcand` · jervcode `/rcand` · OpenBot the `rcand` skill (loaded by name).
@@ -27,7 +27,7 @@ mmi-cli oracle org project get {owner}/{repo} --json
 mmi-cli devops train doctor --lane rcand --heal --json
 ```
 
-Parse stdout only (never `2>&1`). `ready` false → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. Findings carry `code`, `severity`, `source`, `remedy`, `anchor`. `--apply` re-runs the doctor.
+Read it per [train-common.md](../release/train-common.md#doctor).
 
 ## Apply
 
@@ -57,19 +57,15 @@ On any failure or interruption, read [recovery.md](recovery.md).
 
 ## Merge floor
 
-- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag, so tag-anchored checks mis-read. Any merge that carries an already-tagged commit — the `main → development` roll-forward, an alignment PR, a hotfix fold PR — lands as a true merge: `mmi-cli devops pr merge <number> --auto --merge` (or `--wait --merge`); `--wait` alone still squashes. The hotfix main-base PR itself may squash: its tag lands after, on the merged `main` HEAD, and the `-x` trailer must survive the squash message.
-- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt — doctor blocker, authority probe, coverage guard, untolerated conflict, required checks, stray tag, ledger — ends the run. Fix the cause on `development` through a normal PR and rerun the train; never hand-resolve on `main`, hand-cherry-pick, bare-push a train branch, ack to save time, or bypass a check.
-- **Probe the latest Release tag, not branches or stale local tags (#2734).** Queue: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json`; gh rejects `mergeQueueEntry`.
-- **One train per repo (#5380).** Overlapping trains race tags; never start one to help another.
-- **Tag and Release deletion need Jervaise's yes (principle 12),** named in the guide entry that prescribes it.
+Ordinary development PRs land with `mmi-cli devops pr land <number>`. Merges that carry a tagged commit (roll-forward, alignment, fold PR) are true merges, and a refused train is a stop, never finished by hand: the full floor is in [train-common.md](../release/train-common.md#merge-floor). Queue state: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json` (gh rejects `mergeQueueEntry`).
 
 ## Report
 
-Verdict first: the resolved tag (never a placeholder like `vX.Y.0`), Release URL, `releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`, each run's conclusion and URL (or the no-run-URL note), which run is red (deploy/publish verdict or ordinary CI), `announceNote`, the alignment note (`devRollForward`, `rcAlignment` or the fold PR), `checkout`, the dispatch used. Pending is unverified, never success. Product names only when releasing that product's repo.
+Verdict first, per [train-common.md](../release/train-common.md#report): the rc tag (never a placeholder like `vX.Y.0-rc.N`), no Release URL at rc, and the receipt fields above.
 
 ## Retro
 
-Before the final report: did this skill misfire? Process only. If yes, file one lesson (hard cap: one per run); a clean run is silent; if the call fails, note it and continue. Lessons are deduplicated on the owning board and change the skill only by reviewed PR, never live; no issue references outside Merge floor.
+Shared rules: [train-common.md](../release/train-common.md#retro).
 
 ```bash
 mmi-cli learning skill-lesson --skill rcand --title "<what misfired>" --body "<what; evidence; proposed amendment>"

package/skills/rcand/recovery.md

@@ -1,10 +1 @@
-Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. That guide is test-parsed, never free text — the infra drift and plugin-set suites validate every anchor cited here and assert policy from its wording — so an edit to it re-runs the infra suite (`npm --prefix infra test`) in the same PR: a heading or slug change is a code change. A candidate whose immutable rc tag passed policy but whose `origin/rc` was not pushed continues with `mmi-cli devops rcand --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags, and `--apply` mints the next `-rc.N` for a new cut only. A promoted candidate whose rc deploy failed retries it, once the cause is fixed, with `mmi-cli devops rcand --retry-deploy --watch --json --out <fresh-receipt>` — same tag and SHA, never re-cut or re-pushed; `--resume` only re-reads that failed leg. Supersede is the last resort, with the authorized human's fresh approval. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun; a rejected protected push leaves the local tag for an authorized rerun, never a force.
-
-
-## Field reference (moved from SKILL.md)
-
-**Argument:** `/rcand minor`, `/rcand major`, or `/rcand patch` — a bare bump word, never a `--flag` or env var. No argument → `patch`; declare `minor` or `major` for a planned feature cycle.
-
-The JSON is on stdout alone; a stale CLI first prints its self-update notice on stderr and re-runs itself, so parse stdout only, never `2>&1`. Read `ready`, then `findings[]`: each carries `code`, `severity` (`blocker` · `warning` · `healed` · `info`), `source` (`local` · `origin`), `remedy` and `anchor`. `ready: false` → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. `--apply` re-runs this doctor as its step 0 with heal on.
-
-- `deployStatus` — `pending` is never terminal. `runId` / `runUrl` / `workflowRuns` name the run: the dispatched `tenant-deploy.yml` for tenant-container, the auto-fired `deploy.yml` for serverless. Watch each non-success entry to conclusion: `mmi-cli devops read run watch <run-id> --repo {owner}/{repo} --exit-status --interval 60`.
+Every refusal and every doctor blocker names its `code` and `anchor`: open the finding's `anchor` URL and follow that entry, nothing else ([shared recovery](../release/train-common.md#recovery)). A candidate whose immutable rc tag passed policy but whose `origin/rc` was not pushed continues with `mmi-cli devops rcand --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags, and `--apply` mints the next `-rc.N` for a new cut only. A promoted candidate whose rc deploy failed retries it, once the cause is fixed, with `mmi-cli devops rcand --retry-deploy --watch --json --out <fresh-receipt>` — same tag and SHA, never re-cut or re-pushed; `--resume` only re-reads that failed leg. Supersede is the last resort, with the authorized human's fresh approval. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun; a rejected protected push leaves the local tag for an authorized rerun, never a force.

package/skills/rcand/suite.md

@@ -1,4 +1,4 @@
 In the suite lead (MM-Work) a plain rcand, release or hotfix refuses: the suite path is `mmi-cli devops suite rcand --owner-go` or `mmi-cli devops suite release --owner-go` (a lead-only cut needs `--suite-solo --owner-go`). `--owner-go` records Jervaise's explicit go for that one cut; it is never the agent's own flag. Never pass it on your own authority: a held train or a stale MM-Work cut (`suite abandon --owner-go`, then `suite rcand --owner-go`) is handed to the suite orchestrator with that exact command sequence, and runs only after the owner says go. On your own, run only the read-only previews `mmi-cli devops suite rcand --dry-run` and `mmi-cli devops suite hotfix <member> --dry-run`; `suite release` and `suite abandon` have no dry-run, so never run them yourself. A real suite rcand, release, hotfix or abandon runs only on the owner's go, executed by the owner or the suite orchestrator. A suite member cannot run standalone rcand, release or hotfix: cut from the suite lead; only a backward-compatible solo backend release/hotfix with explicit owner approval may pass `--suite-solo --owner-go`, and its MM-Work development pin PR must land before the suite is in sync.
 
-Support sessions (MMI-Hub, Jerv-Hub, Jerv-JervCode) are not suite members and hold standing owner authorization (2026-10-25) to cut and ship releases at their discretion during suite runs without repeated per-release approval; record this standing rule in every suite session's working note and briefing while keeping all standard release preflight, gate, and verification checks.
+Support sessions (MMI-Hub, Jerv-Hub, Jerv-JervCode) are not suite members and hold standing owner authorization (2026-10-25) to cut and ship releases at their discretion during suite runs without repeated per-release approval, and under the owner's 2026-11-01 ruling each support session strives during a suite run to finish its own board and cut a patch release for landed-but-unreleased merges so suite members pick the update up in that run instead of waiting for a later cut, keeping all standard release preflight, gate, and verification checks.
 

package/skills/release/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: release
-description: Ship rc or direct-track development to main and production.
+description: Ship rc or direct-track development to main and production. Use for a production release, not for a candidate (rcand) or an urgent merged fix (hotfix).
 ---
 
 **Host-native invocation:** Claude `/mmi:release` · Codex `$mmi:release` · jervcode `/release` · OpenBot the `release` skill (loaded by name). A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
 
 # /release — ship to main + prod
 
-Bare `minor|major|patch` (default `patch`), never a flag; needs Jervaise's yes (principle 12). Support sessions (`MMI-Hub`, `Jerv-Hub`, `Jerv-JervCode`) hold standing owner authorization (2026-10-25) to release at their discretion during active suite runs without repeated per-release approval; record this standing rule in every suite session's working note and briefing ([suite.md](suite.md)). All standard release preflight, gate, and verification checks still apply. `minor`: `MMI_BUMP_REASON`. `major`: also `MMI_MAJOR_APPROVED=<exact version>` after the yes ([docs/versioning.md](../../docs/versioning.md)).
+Bare `minor|major|patch` (default `patch`), never a flag. A production release normally needs Jervaise's yes unless a standing authorization covers this repo. Support sessions (`MMI-Hub`, `Jerv-Hub`, `Jerv-JervCode`) hold such a standing owner authorization (2026-10-25) to release at their discretion during active suite runs without repeated per-release approval ([suite.md](suite.md)). All standard release preflight, gate, and verification checks still apply. `minor`: `MMI_BUMP_REASON`. `major`: also `MMI_MAJOR_APPROVED=<exact version>` after the yes (bump rules: [verification.md](verification.md)).
 
 ## Lane
 
@@ -15,7 +15,7 @@ Read `mmi-cli oracle org project get {owner}/{repo} --json` and name the lane ([
 
 ## Preflight
 
-`mmi-cli devops train doctor --lane release --heal --json` (stdout only): `ready`, `findings[]` (`code`, `severity`, `source`, `remedy`, `anchor`). `ready: false` → quote blockers' `code` and `remedy`.
+`mmi-cli devops train doctor --lane release --heal --json`; read it per [train-common.md](train-common.md#doctor).
 
 ## Apply
 
@@ -27,7 +27,7 @@ mktemp .jerv/tmp/release-receipt.XXXXXX
 mmi-cli devops release --apply --watch --announce-summary-file "<summary-path>" --json --out "<result-path>"
 ```
 
-MMI-Hub itself releases through the `hub-release` workflow instead: an org owner runs `gh workflow run hub-release.yml --repo mutmutco/MMI-Hub --ref development -f summary='line | line | line'` and watches that run; never build a Hub release on a workstation.
+MMI-Hub itself releases through the `hub-release` workflow instead: an org owner runs `gh workflow run hub-release.yml --repo mutmutco/MMI-Hub --ref development -f summary='line | line | line'` and watches that run; never build a Hub release on a workstation. The board needs no touch: items reached `Done` when their PRs merged to `development`.
 
 Run mktemp alone, copy its path; no channel: drop the summary flag. `mmi-cli devops release --apply --ack <sha>` only for a verified main-only commit the hotfix-coverage guard refused. It runs the version fold (automatic, inside `mmi-cli devops release --apply`) bumping manifests unconditionally, pushes the tag first (`gate.yml` runs on `v*` tags), deploys (`tenant-deploy.yml` for tenant-container), announces. Nothing by hand.
 
@@ -41,19 +41,15 @@ On failure or a pending ledger leg: [recovery.md](recovery.md).
 
 ## Merge floor
 
-- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag, so tag-anchored checks mis-read. Any merge that carries an already-tagged commit — the `main → development` roll-forward, an alignment PR, a hotfix fold PR — lands as a true merge: `mmi-cli devops pr merge <number> --auto --merge` (or `--wait --merge`); `--wait` alone still squashes. The hotfix main-base PR itself may squash: its tag lands after, on the merged `main` HEAD, and the `-x` trailer must survive the squash message.
-- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt — doctor blocker, authority probe, coverage guard, untolerated conflict, required checks, stray tag, ledger — ends the run. Fix the cause on `development` through a normal PR and rerun the train; never hand-resolve on `main`, hand-cherry-pick, bare-push a train branch, ack to save time, or bypass a check.
-- **Probe the latest Release tag, not branches or stale local tags (#2734).** Queue: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json`; gh rejects `mergeQueueEntry`.
-- **One train per repo (#5380).** Overlapping trains race tags; never start one to help another.
-- **Tag and Release deletion need Jervaise's yes (principle 12),** named in the guide entry that prescribes it.
+Ordinary development PRs land with `mmi-cli devops pr land <number>`. Merges that carry a tagged commit (roll-forward, alignment, fold PR) are true merges, and a refused train is a stop, never finished by hand: the full floor is in [train-common.md](train-common.md#merge-floor). Queue state: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json` (gh rejects `mergeQueueEntry`).
 
 ## Report
 
-Verdict first: the resolved tag (never a placeholder like `vX.Y.0`), Release URL, `releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`, each run's conclusion and URL (or the no-run-URL note), which run is red (deploy/publish verdict or ordinary CI), `announceNote`, the alignment note (`devRollForward`, `rcAlignment` or the fold PR), `checkout`, the dispatch used. Pending is unverified, never success. Product names only when releasing that product's repo.
+Verdict first, per [train-common.md](train-common.md#report): the resolved tag (never a placeholder like `vX.Y.0`), Release URL, and the receipt fields in [verification.md](verification.md).
 
 ## Retro
 
-Before the final report: did this skill misfire? Process only. If yes, file one lesson (hard cap: one per run); a clean run is silent; if the call fails, note it and continue. Lessons are deduplicated on the owning board and change the skill only by reviewed PR, never live; no issue references outside Merge floor.
+Shared rules: [train-common.md](train-common.md#retro).
 
 ```bash
 mmi-cli learning skill-lesson --skill release --title "<what misfired>" --body "<what; evidence; proposed amendment>"

package/skills/release/recovery.md

@@ -1,7 +1,6 @@
 # Release recovery and ledger continuation
 
-
-Every refusal and every doctor blocker names its `code` and `anchor`: open `docs/Guides/train-troubleshooting.md#<code>` and follow that entry, nothing else. That guide is test-parsed, never free text — the infra drift and plugin-set suites validate every anchor cited here and assert policy from its wording — so an edit to it re-runs the infra suite (`npm --prefix infra test`) in the same PR: a heading or slug change is a code change. A pre-tag abort with no finding code (for example, a transient secrets-preflight timeout) is a transient stop: nothing was promoted and no tag was cut. Confirm no tag reached origin (`git ls-remote --tags origin`), then rerun `mmi-cli devops release --apply` as a fresh cut, never `--resume`; resume is only for a partial release with the tag already on origin. A partial release (tag on origin, later phases pending or failed) continues with `mmi-cli devops release --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags or republishes, posts a deferred announcement only when it is the run that first proves deploy and publish green, and `--apply` belongs to a new cut only. A SUPERSEDED leg is not a pending one: a ledger that records a supersession is phases-green — `--resume` must not be used on it, and the deferred announcement is the next patch train's to carry. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun.
+Every refusal and every doctor blocker names its `code` and `anchor`: open the finding's `anchor` URL and follow that entry, nothing else ([shared recovery](train-common.md#recovery)). A pre-tag abort with no finding code (for example, a transient secrets-preflight timeout) is a transient stop: nothing was promoted and no tag was cut. Confirm no tag reached origin (`git ls-remote --tags origin`), then rerun `mmi-cli devops release --apply` as a fresh cut, never `--resume`; resume is only for a partial release with the tag already on origin. A partial release (tag on origin, later phases pending or failed) continues with `mmi-cli devops release --resume --watch --json --out <fresh-receipt>` — the only continuation form: `--resume` never re-tags or republishes, posts a deferred announcement only when it is the run that first proves deploy and publish green, and `--apply` belongs to a new cut only. A SUPERSEDED leg is not a pending one: a ledger that records a supersession is phases-green — `--resume` must not be used on it, and the deferred announcement is the next patch train's to carry. A refused train is a stop (Merge floor): fix the cause on `development` through a normal PR, then rerun.
 
 **Exactly one continuation per ledger state.** Pick the row, run its verb, never combine two:
 

package/skills/release/suite.md

@@ -1,6 +1,6 @@
 In the suite lead (MM-Work) a plain rcand, release or hotfix refuses: the suite path is `mmi-cli devops suite rcand --owner-go` or `mmi-cli devops suite release --owner-go` (a lead-only cut needs `--suite-solo --owner-go`). `--owner-go` records Jervaise's explicit go for that one cut; it is never the agent's own flag. Never pass it on your own authority: a held train or a stale MM-Work cut (`suite abandon --owner-go`, then `suite rcand --owner-go`) is handed to the suite orchestrator with that exact command sequence, and runs only after the owner says go. On your own, run only the read-only previews `mmi-cli devops suite rcand --dry-run` and `mmi-cli devops suite hotfix <member> --dry-run`; `suite release` and `suite abandon` have no dry-run, so never run them yourself. A real suite rcand, release, hotfix or abandon runs only on the owner's go, executed by the owner or the suite orchestrator. A suite member cannot run standalone rcand, release or hotfix: cut from the suite lead; only a backward-compatible solo backend release/hotfix with explicit owner approval may pass `--suite-solo --owner-go`, and its MM-Work development pin PR must land before the suite is in sync.
 
-Support sessions (MMI-Hub, Jerv-Hub, Jerv-JervCode) are not suite members and hold standing owner authorization (2026-10-25) to cut and ship releases at their discretion during suite runs without repeated per-release approval; record this standing rule in every suite session's working note and briefing while keeping all standard release preflight, gate, and verification checks.
+Support sessions (MMI-Hub, Jerv-Hub, Jerv-JervCode) are not suite members and hold standing owner authorization (2026-10-25) to cut and ship releases at their discretion during suite runs without repeated per-release approval, and under the owner's 2026-11-01 ruling each support session strives during a suite run to finish its own board and cut a patch release for landed-but-unreleased merges so suite members pick the update up in that run instead of waiting for a later cut, keeping all standard release preflight, gate, and verification checks.
 
 Every new mm-work suite Release (including solo and hotfix releases) requires both `--announce-summary-file <path>` (English) and `--announce-summary-file-tr <path>` (Turkish, "sen" form) in the update-notes template. The canonical wording lives in the [MM-Work GUIDE, "Update notes"](https://github.com/mutmutco/MM-Work/blob/development/packages/mmwork-ds/GUIDE.md#update-notes); this repo links it and never copies it. Each file has the section word `Fixed` / `Düzeldi` (what works now, never the problem: "Drive: Scans of large drives now finish without timing out."; a line without now / again / no longer, or artık / yeniden / tekrar / yine, is refused) and/or `New` / `Yeni` (what you can now do) on its own line, Fixed first, each only when it has lines. Under them go 1–8 lines of `<Area>: <sentence>.`, each at most 120 characters, with no issue numbers, versions or commit prefixes. Off-template or missing files refuse before tagging. Do not write the head (app · date · time) or the thanks line: MM-Work renders both from the Release date and credits. Suite release also requires a valid `--member-summary-file <owner/repo=path>` and `--member-summary-file-tr <owner/repo=path>` for every member being released, before promoting any member. Carried, held and already-released members need none, and existing Releases can resume without new files.
 The `/user-releases` feed serves template notes as `updateNotes: {en?, tr?: {fixed[], new[]}}`. Older title-and-notes bodies keep `plainWords` and get `updateNotes: null`.

package/skills/release/train-common.md

@@ -0,0 +1,28 @@
+# Train skills: shared doctor, recovery, merge floor, report and retro
+
+`/release`, `/rcand` and `/hotfix` read this one file (from a sibling skill: `../release/train-common.md`). Each skill keeps only what differs by lane.
+
+## Doctor
+
+The preflight JSON is on stdout alone: a stale CLI first prints its self-update notice on stderr and re-runs itself, so parse stdout only, never `2>&1`. Read `ready`, then `findings[]`: each carries `code`, `severity` (`blocker` · `warning` · `healed` · `info`), `source` (`local` · `origin`), `remedy` and `anchor`. `ready: false` → stop and quote every blocker's `code` and `remedy`; an unread origin is never green. The apply step (`release --apply`, `rcand --apply`, `hotfix start`, `hotfix release`) re-runs the doctor first, with heal on.
+
+## Recovery
+
+Every refusal and every doctor blocker names its `code` and `anchor`: open the finding's `anchor` URL and follow that entry, nothing else. The CLI emits the URL; a product repo carries no local copy of the guide.
+
+## Merge floor
+
+- **Ordinary development PRs land with `mmi-cli devops pr land <number>`.** The rules below are for the train's own merges.
+- **Never squash-merge a tagged commit (#3167).** A squash re-mints the SHA and orphans the tag, so tag-anchored checks mis-read. Any merge that carries an already-tagged commit — the `main → development` roll-forward, an alignment PR, a hotfix fold PR — lands as a true merge: `mmi-cli devops pr merge <number> --auto --merge` (or `--wait --merge`); `--wait` alone still squashes. The hotfix main-base PR itself may squash: its tag lands after, on the merged `main` HEAD, and the `-x` trailer must survive the squash message.
+- **A refused train is a stop, never a license to finish by hand.** Every fail-closed halt — doctor blocker, authority probe, coverage guard, untolerated conflict, required checks, stray tag, ledger — ends the run. Fix the cause on `development` through a normal PR and rerun the train; never hand-resolve on `main`, hand-cherry-pick, bare-push a train branch, ack to save time, or bypass a check.
+- **Probe the latest Release tag, not branches or stale local tags (#2734).** Queue: `mmi-cli devops read pr queue <number> --repo <owner/repo> --json`; gh rejects `mergeQueueEntry`.
+- **One train per repo (#5380).** Overlapping trains race tags; never start one to help another.
+- **Tag and Release deletion need Jervaise's yes (principle 12),** named in the guide entry that prescribes it.
+
+## Report
+
+Verdict first: the resolved tag (never a placeholder like `vX.Y.0`), Release URL (none at rc), `releaseStatus`, `followUpStatus`, `deployStatus`, `promoted`, each run's conclusion and URL (or the no-run-URL note), which run is red (deploy/publish verdict or ordinary CI), `announceNote`, the alignment note (`devRollForward`, `rcAlignment` or the fold PR), `checkout`, the dispatch used. Pending is unverified, never success. Product names only when releasing that product's repo.
+
+## Retro
+
+Before the final report: did this skill misfire? Process only. If yes, file one lesson with the skill's own Retro command (hard cap: one per run); a clean run is silent; if the call fails, note it and continue. Lessons are deduplicated on the owning board and change the skill only by reviewed PR, never live.