1 · Hotfix forward

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 1 · Hotfix forward
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/hotfix/01-hotfix/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 5
- part_number: 1 (legacy stepNumber frontmatter)
- legacy_step_number: 1
- est_time: ~15 min – 1 hr
- description: Branch from production state, make the minimal scoped fix, fast-track straight to production skipping staging, then back-merge so the fix survives the next release.
- tags: codecanyon, laravel, hotfix, incident, deployer, migrations

## Execution rules (binding)
- This is Part 1 of phase 5 (~15 min – 1 hr) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 1 · Hotfix forward

## TL;DR

**Objective** — patch a live, broken app the fast-but-safe way: branch from the **production** state (not `develop`), make the smallest possible fix, deploy straight to production skipping staging, then back-merge so the fix isn't lost on the next release.

:::note[User part + done-when]
**👤 User part** — the **production deploy itself is human-gated**: a person runs the production push + `dep deploy production`. Plus two more human checkpoints — confirm the production fix actually works in the browser, and approve before the hotfix branch is deleted. Everything else (branch, commit, the hotfix-branch merge, tag, back-merge into `main`/`develop`/`staging`) an agent can drive — but the live-server promotion stays fenced to a human, same as branch-protection and live-payment actions.

**Done when** production works again, the fix is tagged, and it's been merged into `main`, `develop`, and `staging` so the next release keeps it. &nbsp;·&nbsp; **⏱ ~15 min – 1 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 git/back-merge, 👤 production deploy + verify).
:::

## Background

The thing that makes a hotfix different from a normal deploy is **where you branch from**. A normal change starts on `develop` and flows through the selected non-production target from `Zaj-PROJECT.md` before production. A hotfix can't wait for that — production is already broken, and `develop` may contain half-finished work you don't want live. So you branch straight from `production`, fix only the one thing, and deploy directly.

That speed has a cost: the fix now lives only on the production line, not in `develop`. If you stop there, the **next** normal release silently overwrites your fix and the bug comes back. That's why Phase 3 (back-merge) is not optional — it's the step that makes the fix permanent.

Read `Zaj-PROJECT.md` before touching production. It tells you the production SSH alias, deploy path, PHP binary, branch model, and any extra non-production branches (`staging`, `qa`, `uat`, `client-demo`) that need the fix after production is stable. If the hotfix changes runtime/dependency/deploy facts, rerun the relevant parity check and update `Zaj-PROJECT.md` plus `.tool-versions`; otherwise mark parity `N/A` with evidence in `Zaj-PROGRESS.md`.

Before calling SSH credentials missing, discover existing aliases:

```bash
grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
PHPBIN="<production-cli-php-from-Zaj-PROJECT>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_PRODUCTION_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; alias/host/user/port match the production row
```

```mermaid
flowchart LR
  P[production] -->|branch from| H[Hotfix/fix-description]
  H -->|deploy direct| P2[production live]
  H -->|back-merge| D[develop]
  D --> S[non-production branches]
  P2 -->|merge| M[main]
```

## Steps

### 1. Assess before you touch anything

Spend two minutes confirming it's a true emergency and that you understand the bug. A wrong fix deployed in a panic is worse than the original break.

<Steps>

1. **Read the production error log and recent deploys.** Find the actual error before writing any fix.

   ```bash
   ssh [SSH_PRODUCTION_ALIAS] "tail -50 [DEPLOY_PATH]/storage/logs/laravel.log"
   git log --oneline production -5
   # Expected: a stack trace / error message, and the last 5 production commits
   ```

   - ✅ You can name what's broken and, if a deploy caused it, which one.

2. **Decide: hotfix or roll back.** If you can fix it in under an hour, continue here. If not — or if the last deploy is the culprit — switch to [Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/) and restore the last good release first.

   - ✅ You've chosen to fix forward, and you know the fix.

</Steps>

:::caution[Don't panic-deploy]
If you can't clearly explain the bug yet, you're not ready to hotfix. Roll back to buy time, then diagnose calmly — a broken fix on top of a broken app doubles the damage.
:::

### 2. Branch from production and fix

Branch from `production` itself — **not** `develop` — so your fix sits on exactly the code that's live, with nothing extra coming along for the ride.

<Steps>

1. **Branch from the live production state.**

   ```bash
   git checkout production && git pull origin production
   git checkout -b Hotfix/fix-description
   # Expected: now on Hotfix/fix-description, branched off current production
   ```

   - ✅ `git branch --show-current` prints `Hotfix/fix-description`.

2. **Make the minimal fix, test locally, and commit.** Change only what's needed to stop the bleeding — no refactors, no extras.

   ```bash
   # find and fix the bug, then a quick local test
   git commit -am "🔧 🟦 T2 Fix-Bug: Fix [description]"
   git push origin Hotfix/fix-description
   # Expected: one small commit pushed to the hotfix branch
   ```

   - ✅ The fix is a small, scoped diff and is pushed to the remote.

</Steps>

A hotfix that touches twenty files isn't a hotfix — it's a feature in disguise. Keep the diff small enough to review at a glance under pressure.

:::caution[Does the fix change the database schema?]
If the hotfix adds a migration, it inherits the full database safety gate — review `php artisan migrate:status` + `migrate --pretend`, run `atlas migrate lint`, and **take a verified DB dump before any destructive op** (`DROP`/`MODIFY COLUMN`/`migrate:fresh` — see [Ship → DB gate](/tech-stack/laravel/codecanyon/build/playbooks/continuous-deploy/01-ship/)). A schema mistake shipped under panic is far harder to undo than the bug you're fixing. If the fix is schema-heavy, that's a sign it isn't a hotfix — roll back and ship it the staged way instead.
:::

:::danger[Does the fix touch `vendor/`?]
A genuine hotfix branches from clean `production` and changes only app code — it should **not** modify `vendor/`. If you must change a vendor package (or restore one), do **not** `composer install` over a CodeCanyon tree — already-locked packages are skipped and any tampering persists. Force a clean replacement (`composer reinstall <vendor>/<package>` or `rm -rf vendor && composer install`) and re-run the backdoor-signature scan + `grep -r 'getCourant|envato\.|verify\.js|HeaderCodec' vendor/` (see [Extract & snapshot the vendor](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/03-extract-and-snapshot/)) before deploying. Never preserve a vendor diff into the deploy without classifying it first.
:::

### 3. Deploy straight to production

This is the one workflow where you **skip staging on purpose**. Production is already broken, so the normal staged path would only extend the outage. Merge the hotfix into `production` and deploy.

<Steps>

1. **Merge and deploy to production. 👤 USER step — production is human-gated.** If the fix includes a migration, confirm the verified DB dump from §2 exists *before* deploying — the deploy runs migrations. **Who runs this — 👤 you (production is human-gated).** The agent prepares the hotfix branch, the merge, and the DB/vendor guards; a human runs the actual production push + deploy. Even under incident pressure, agents stay fenced from production deploys (real-user / real-money actions) — the same gating as branch-protection and live payments.

   ```bash
   git checkout production
   git merge Hotfix/fix-description
   git push origin production
   dep deploy production
   # Expected: deployer publishes a new release, runs migrations, and switches the live symlink.
   # storage/ is a shared dir → uploads + the storage/installed marker carry over untouched.
   ```

   - ✅ 👤 You ran the production deploy; it completes without errors and the new release is live (DB dump on hand if a migration ran).

</Steps>

Now hand off to a person for the one check an agent can't truly make — does it actually work for a real user?

:::note[Who does this]
👤 **User** opens the live site and confirms the broken thing is fixed — and that nothing obvious else broke. Only a human can judge "the app works now."
:::

Open production in a browser, reproduce the original failing action, and confirm it now succeeds before moving on.

### 4. Make the fix permanent (back-merge)

The fix is live but fragile — it exists only on the production line. Tag it, then fold it back into every branch so the next normal release can't undo it.

<Steps>

1. **Tag the fix and propagate it to `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.**

   ```bash
   NON_PROD_BRANCH="staging" # example; repeat for each selected non-production branch in Zaj-PROJECT.md
   git tag v[VERSION]-[next letter]   # e.g. v1.0.0-a → v1.0.0-b
   git push origin v[VERSION]-[next letter]

   git checkout main && git merge production && git push origin main
   git checkout develop && git merge Hotfix/fix-description && git push origin develop
   git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
   # Expected: the fix now exists on main, develop, and every configured non-production branch
   ```

   - ✅ `git branch --contains Hotfix/fix-description` lists `develop` (and the fix is on `main` plus every configured non-production branch).

</Steps>

This back-merge is the difference between fixing the bug once and fixing it forever. Skip it and the bug reappears on the next deploy from `develop`.

:::note[Who does this]
👤 **User** confirms the incident is fully resolved before the throwaway branch is removed — the branch is the only record of the isolated fix until it's safely merged everywhere.
:::

Once a person has confirmed everything is merged and stable, clean up:

```bash
git checkout develop
# then delete the hotfix branch (local + remote) once 👤 confirms it's safe
```

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Assessed** — production error read; confirmed it's a true emergency and the fix is understood.
- [ ] **🤖 Branched from production** — on `Hotfix/fix-description`, off the live state (not `develop`).
- [ ] **🔀 Minimal fix shipped** — 🤖 agent prepared the small scoped diff and merge; **👤 you ran the production push + `dep deploy production`** (production is human-gated) and it succeeded.
- [ ] **🔀 DB / vendor guards cleared** — if the fix added a migration, a **verified DB dump was taken first** and `migrate --pretend`/Atlas lint reviewed; if it touched `vendor/`, the package was clean-reinstalled (not `composer install`) and re-scanned for backdoor signatures. (Skip if the fix is app-code-only.)
- [ ] **👤 Verified live** — the original failure is reproduced and confirmed fixed in a browser on production.
- [ ] **🤖 Tagged + back-merged** — `v[VERSION]-[next letter]` pushed; fix merged into `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.
- [ ] **👤 Cleanup approved** — incident confirmed resolved before the hotfix branch is deleted.

:::next[Next step]
[Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/)
:::

# 1 · Hotfix forward

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/hotfix/01-hotfix/

## TL;DR

**Objective** — patch a live, broken app the fast-but-safe way: branch from the **production** state (not `develop`), make the smallest possible fix, deploy straight to production skipping staging, then back-merge so the fix isn't lost on the next release.

:::note[User part + done-when]
**👤 User part** — the **production deploy itself is human-gated**: a person runs the production push + `dep deploy production`. Plus two more human checkpoints — confirm the production fix actually works in the browser, and approve before the hotfix branch is deleted. Everything else (branch, commit, the hotfix-branch merge, tag, back-merge into `main`/`develop`/`staging`) an agent can drive — but the live-server promotion stays fenced to a human, same as branch-protection and live-payment actions.

**Done when** production works again, the fix is tagged, and it's been merged into `main`, `develop`, and `staging` so the next release keeps it. &nbsp;·&nbsp; **⏱ ~15 min – 1 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 git/back-merge, 👤 production deploy + verify).
:::

## Background

The thing that makes a hotfix different from a normal deploy is **where you branch from**. A normal change starts on `develop` and flows through the selected non-production target from `Zaj-PROJECT.md` before production. A hotfix can't wait for that — production is already broken, and `develop` may contain half-finished work you don't want live. So you branch straight from `production`, fix only the one thing, and deploy directly.

That speed has a cost: the fix now lives only on the production line, not in `develop`. If you stop there, the **next** normal release silently overwrites your fix and the bug comes back. That's why Phase 3 (back-merge) is not optional — it's the step that makes the fix permanent.

Read `Zaj-PROJECT.md` before touching production. It tells you the production SSH alias, deploy path, PHP binary, branch model, and any extra non-production branches (`staging`, `qa`, `uat`, `client-demo`) that need the fix after production is stable. If the hotfix changes runtime/dependency/deploy facts, rerun the relevant parity check and update `Zaj-PROJECT.md` plus `.tool-versions`; otherwise mark parity `N/A` with evidence in `Zaj-PROGRESS.md`.

Before calling SSH credentials missing, discover existing aliases:

```bash
grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
PHPBIN="<production-cli-php-from-Zaj-PROJECT>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_PRODUCTION_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; alias/host/user/port match the production row
```

```mermaid
flowchart LR
  P[production] -->|branch from| H[Hotfix/fix-description]
  H -->|deploy direct| P2[production live]
  H -->|back-merge| D[develop]
  D --> S[non-production branches]
  P2 -->|merge| M[main]
```

## Steps

### 1. Assess before you touch anything

Spend two minutes confirming it's a true emergency and that you understand the bug. A wrong fix deployed in a panic is worse than the original break.

<Steps>

1. **Read the production error log and recent deploys.** Find the actual error before writing any fix.

   ```bash
   ssh [SSH_PRODUCTION_ALIAS] "tail -50 [DEPLOY_PATH]/storage/logs/laravel.log"
   git log --oneline production -5
   # Expected: a stack trace / error message, and the last 5 production commits
   ```

   - ✅ You can name what's broken and, if a deploy caused it, which one.

2. **Decide: hotfix or roll back.** If you can fix it in under an hour, continue here. If not — or if the last deploy is the culprit — switch to [Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/) and restore the last good release first.

   - ✅ You've chosen to fix forward, and you know the fix.

</Steps>

:::caution[Don't panic-deploy]
If you can't clearly explain the bug yet, you're not ready to hotfix. Roll back to buy time, then diagnose calmly — a broken fix on top of a broken app doubles the damage.
:::

### 2. Branch from production and fix

Branch from `production` itself — **not** `develop` — so your fix sits on exactly the code that's live, with nothing extra coming along for the ride.

<Steps>

1. **Branch from the live production state.**

   ```bash
   git checkout production && git pull origin production
   git checkout -b Hotfix/fix-description
   # Expected: now on Hotfix/fix-description, branched off current production
   ```

   - ✅ `git branch --show-current` prints `Hotfix/fix-description`.

2. **Make the minimal fix, test locally, and commit.** Change only what's needed to stop the bleeding — no refactors, no extras.

   ```bash
   # find and fix the bug, then a quick local test
   git commit -am "🔧 🟦 T2 Fix-Bug: Fix [description]"
   git push origin Hotfix/fix-description
   # Expected: one small commit pushed to the hotfix branch
   ```

   - ✅ The fix is a small, scoped diff and is pushed to the remote.

</Steps>

A hotfix that touches twenty files isn't a hotfix — it's a feature in disguise. Keep the diff small enough to review at a glance under pressure.

:::caution[Does the fix change the database schema?]
If the hotfix adds a migration, it inherits the full database safety gate — review `php artisan migrate:status` + `migrate --pretend`, run `atlas migrate lint`, and **take a verified DB dump before any destructive op** (`DROP`/`MODIFY COLUMN`/`migrate:fresh` — see [Ship → DB gate](/tech-stack/laravel/codecanyon/build/playbooks/continuous-deploy/01-ship/)). A schema mistake shipped under panic is far harder to undo than the bug you're fixing. If the fix is schema-heavy, that's a sign it isn't a hotfix — roll back and ship it the staged way instead.
:::

:::danger[Does the fix touch `vendor/`?]
A genuine hotfix branches from clean `production` and changes only app code — it should **not** modify `vendor/`. If you must change a vendor package (or restore one), do **not** `composer install` over a CodeCanyon tree — already-locked packages are skipped and any tampering persists. Force a clean replacement (`composer reinstall <vendor>/<package>` or `rm -rf vendor && composer install`) and re-run the backdoor-signature scan + `grep -r 'getCourant|envato\.|verify\.js|HeaderCodec' vendor/` (see [Extract & snapshot the vendor](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/03-extract-and-snapshot/)) before deploying. Never preserve a vendor diff into the deploy without classifying it first.
:::

### 3. Deploy straight to production

This is the one workflow where you **skip staging on purpose**. Production is already broken, so the normal staged path would only extend the outage. Merge the hotfix into `production` and deploy.

<Steps>

1. **Merge and deploy to production. 👤 USER step — production is human-gated.** If the fix includes a migration, confirm the verified DB dump from §2 exists *before* deploying — the deploy runs migrations. **Who runs this — 👤 you (production is human-gated).** The agent prepares the hotfix branch, the merge, and the DB/vendor guards; a human runs the actual production push + deploy. Even under incident pressure, agents stay fenced from production deploys (real-user / real-money actions) — the same gating as branch-protection and live payments.

   ```bash
   git checkout production
   git merge Hotfix/fix-description
   git push origin production
   dep deploy production
   # Expected: deployer publishes a new release, runs migrations, and switches the live symlink.
   # storage/ is a shared dir → uploads + the storage/installed marker carry over untouched.
   ```

   - ✅ 👤 You ran the production deploy; it completes without errors and the new release is live (DB dump on hand if a migration ran).

</Steps>

Now hand off to a person for the one check an agent can't truly make — does it actually work for a real user?

:::note[Who does this]
👤 **User** opens the live site and confirms the broken thing is fixed — and that nothing obvious else broke. Only a human can judge "the app works now."
:::

Open production in a browser, reproduce the original failing action, and confirm it now succeeds before moving on.

### 4. Make the fix permanent (back-merge)

The fix is live but fragile — it exists only on the production line. Tag it, then fold it back into every branch so the next normal release can't undo it.

<Steps>

1. **Tag the fix and propagate it to `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.**

   ```bash
   NON_PROD_BRANCH="staging" # example; repeat for each selected non-production branch in Zaj-PROJECT.md
   git tag v[VERSION]-[next letter]   # e.g. v1.0.0-a → v1.0.0-b
   git push origin v[VERSION]-[next letter]

   git checkout main && git merge production && git push origin main
   git checkout develop && git merge Hotfix/fix-description && git push origin develop
   git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
   # Expected: the fix now exists on main, develop, and every configured non-production branch
   ```

   - ✅ `git branch --contains Hotfix/fix-description` lists `develop` (and the fix is on `main` plus every configured non-production branch).

</Steps>

This back-merge is the difference between fixing the bug once and fixing it forever. Skip it and the bug reappears on the next deploy from `develop`.

:::note[Who does this]
👤 **User** confirms the incident is fully resolved before the throwaway branch is removed — the branch is the only record of the isolated fix until it's safely merged everywhere.
:::

Once a person has confirmed everything is merged and stable, clean up:

```bash
git checkout develop
# then delete the hotfix branch (local + remote) once 👤 confirms it's safe
```

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Assessed** — production error read; confirmed it's a true emergency and the fix is understood.
- [ ] **🤖 Branched from production** — on `Hotfix/fix-description`, off the live state (not `develop`).
- [ ] **🔀 Minimal fix shipped** — 🤖 agent prepared the small scoped diff and merge; **👤 you ran the production push + `dep deploy production`** (production is human-gated) and it succeeded.
- [ ] **🔀 DB / vendor guards cleared** — if the fix added a migration, a **verified DB dump was taken first** and `migrate --pretend`/Atlas lint reviewed; if it touched `vendor/`, the package was clean-reinstalled (not `composer install`) and re-scanned for backdoor signatures. (Skip if the fix is app-code-only.)
- [ ] **👤 Verified live** — the original failure is reproduced and confirmed fixed in a browser on production.
- [ ] **🤖 Tagged + back-merged** — `v[VERSION]-[next letter]` pushed; fix merged into `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.
- [ ] **👤 Cleanup approved** — incident confirmed resolved before the hotfix branch is deleted.

:::next[Next step]
[Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/)
:::

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.

Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.

EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

TL;DR

Objective — patch a live, broken app the fast-but-safe way: branch from the production state (not develop), make the smallest possible fix, deploy straight to production skipping staging, then back-merge so the fix isn’t lost on the next release.

Background

The thing that makes a hotfix different from a normal deploy is where you branch from. A normal change starts on develop and flows through the selected non-production target from Zaj-PROJECT.md before production. A hotfix can’t wait for that — production is already broken, and develop may contain half-finished work you don’t want live. So you branch straight from production, fix only the one thing, and deploy directly.

That speed has a cost: the fix now lives only on the production line, not in develop. If you stop there, the next normal release silently overwrites your fix and the bug comes back. That’s why Phase 3 (back-merge) is not optional — it’s the step that makes the fix permanent.

Read Zaj-PROJECT.md before touching production. It tells you the production SSH alias, deploy path, PHP binary, branch model, and any extra non-production branches (staging, qa, uat, client-demo) that need the fix after production is stable. If the hotfix changes runtime/dependency/deploy facts, rerun the relevant parity check and update Zaj-PROJECT.md plus .tool-versions; otherwise mark parity N/A with evidence in Zaj-PROGRESS.md.

Before calling SSH credentials missing, discover existing aliases:

grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
PHPBIN="<production-cli-php-from-Zaj-PROJECT>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_PRODUCTION_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; alias/host/user/port match the production row

flowchart LR
  P[production] -->|branch from| H[Hotfix/fix-description]
  H -->|deploy direct| P2[production live]
  H -->|back-merge| D[develop]
  D --> S[non-production branches]
  P2 -->|merge| M[main]

Steps

1. Assess before you touch anything

Spend two minutes confirming it’s a true emergency and that you understand the bug. A wrong fix deployed in a panic is worse than the original break.

Read the production error log and recent deploys. Find the actual error before writing any fix.

ssh [SSH_PRODUCTION_ALIAS] "tail -50 [DEPLOY_PATH]/storage/logs/laravel.log"
git log --oneline production -5
# Expected: a stack trace / error message, and the last 5 production commits

✅ You can name what’s broken and, if a deploy caused it, which one.

Decide: hotfix or roll back. If you can fix it in under an hour, continue here. If not — or if the last deploy is the culprit — switch to Roll back and restore the last good release first.
- ✅ You’ve chosen to fix forward, and you know the fix.

2. Branch from production and fix

Branch from production itself — not develop — so your fix sits on exactly the code that’s live, with nothing extra coming along for the ride.

Branch from the live production state.

git checkout production && git pull origin production
git checkout -b Hotfix/fix-description
# Expected: now on Hotfix/fix-description, branched off current production

✅ git branch --show-current prints Hotfix/fix-description.

Make the minimal fix, test locally, and commit. Change only what’s needed to stop the bleeding — no refactors, no extras.

# find and fix the bug, then a quick local test
git commit -am "🔧 🟦 T2 Fix-Bug: Fix [description]"
git push origin Hotfix/fix-description
# Expected: one small commit pushed to the hotfix branch

✅ The fix is a small, scoped diff and is pushed to the remote.

A hotfix that touches twenty files isn’t a hotfix — it’s a feature in disguise. Keep the diff small enough to review at a glance under pressure.

3. Deploy straight to production

This is the one workflow where you skip staging on purpose. Production is already broken, so the normal staged path would only extend the outage. Merge the hotfix into production and deploy.

Merge and deploy to production. 👤 USER step — production is human-gated. If the fix includes a migration, confirm the verified DB dump from §2 exists before deploying — the deploy runs migrations. Who runs this — 👤 you (production is human-gated). The agent prepares the hotfix branch, the merge, and the DB/vendor guards; a human runs the actual production push + deploy. Even under incident pressure, agents stay fenced from production deploys (real-user / real-money actions) — the same gating as branch-protection and live payments.
Terminal window
```
git checkout production
git merge Hotfix/fix-description
git push origin production
dep deploy production
# Expected: deployer publishes a new release, runs migrations, and switches the live symlink.
# storage/ is a shared dir → uploads + the storage/installed marker carry over untouched.
```
- ✅ 👤 You ran the production deploy; it completes without errors and the new release is live (DB dump on hand if a migration ran).

Now hand off to a person for the one check an agent can’t truly make — does it actually work for a real user?

Open production in a browser, reproduce the original failing action, and confirm it now succeeds before moving on.

4. Make the fix permanent (back-merge)

The fix is live but fragile — it exists only on the production line. Tag it, then fold it back into every branch so the next normal release can’t undo it.

Tag the fix and propagate it to main, develop, and every non-production branch listed in Zaj-PROJECT.md.

NON_PROD_BRANCH="staging" # example; repeat for each selected non-production branch in Zaj-PROJECT.md
git tag v[VERSION]-[next letter]   # e.g. v1.0.0-a → v1.0.0-b
git push origin v[VERSION]-[next letter]

git checkout main && git merge production && git push origin main
git checkout develop && git merge Hotfix/fix-description && git push origin develop
git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
# Expected: the fix now exists on main, develop, and every configured non-production branch

✅ git branch --contains Hotfix/fix-description lists develop (and the fix is on main plus every configured non-production branch).

This back-merge is the difference between fixing the bug once and fixing it forever. Skip it and the bug reappears on the next deploy from develop.

Once a person has confirmed everything is merged and stable, clean up:

git checkout develop
# then delete the hotfix branch (local + remote) once 👤 confirms it's safe

Checklist

Do not mark this step done until every box below is checked.

🤖 Assessed — production error read; confirmed it’s a true emergency and the fix is understood.
🤖 Branched from production — on Hotfix/fix-description, off the live state (not develop).
🔀 Minimal fix shipped — 🤖 agent prepared the small scoped diff and merge; 👤 you ran the production push + dep deploy production (production is human-gated) and it succeeded.
🔀 DB / vendor guards cleared — if the fix added a migration, a verified DB dump was taken first and migrate --pretend/Atlas lint reviewed; if it touched vendor/, the package was clean-reinstalled (not composer install) and re-scanned for backdoor signatures. (Skip if the fix is app-code-only.)
👤 Verified live — the original failure is reproduced and confirmed fixed in a browser on production.
🤖 Tagged + back-merged — v[VERSION]-[next letter] pushed; fix merged into main, develop, and every non-production branch listed in Zaj-PROJECT.md.
👤 Cleanup approved — incident confirmed resolved before the hotfix branch is deleted.

Roll back

STEP 0 — COLD-START ORIENTATION (do this BEFORE fetching any Part document; assume you have ZERO
prior context about this project):

1. Locate + identify. Run `pwd`. Read the project's `AGENTS.md` + `CLAUDE.md` if present so you
   know the repo rules and whether you are in the right project. Then read `Zaj-PROJECT.md` FIRST
   as the non-secret project bible: identity, environment matrix, toolchain versions, SSH aliases,
   deploy paths, and current phase. If `Zaj-PROJECT.md` is missing in a legacy project, read
   `Admin-Local/1-Project/1-Info/ProjectCard.md` as fallback, then create/update `Zaj-PROJECT.md`.

2. Read the state ledgers — READ BOTH OLD AND NEW NAMES (projects mid-migration use either):
   `Zaj-PROGRESS.md` OR `PROGRESS.md` (what earlier phases/steps already did, what's in-flight),
   `Zaj-BACKLOG.md` OR `BACKLOG.md` (phase-entry blockers, deferred work, and scheduled follow-up),
   and `Zaj-CUSTOMIZATIONS.md` OR `_CUSTOMIZATIONS.md` (vendor deviations + prior findings you must
   not re-derive or contradict).

3. Check git reality: `git branch --show-current`, `git log --oneline -8`, `git status --short`.
   - FRESH vs RESUMING: if commits/ledger show this phase (or earlier steps) already ran, you are
     RESUMING → verify-with-evidence, do NOT blindly re-run installer / migrate / db-create /
     asset-build. (This is the contract's reconcile rule.)
   - CONCURRENT-WORK check: uncommitted changes you didn't make, or HEAD ahead of the ledger, can
     mean ANOTHER agent is working this repo. Coordinate around hot files; do not commit over
     unrelated work. Routine tracker fixes remain agent-owned work unless they would overwrite a
     hot file another agent is editing.

4. Inherit rules + safety: skim `.claude/rules/` (project-specific vendor gotchas) and obey them +
   these non-negotiables — never echo secrets (verify by length/exit-code only), never re-run
   destructive/once-only steps, archive-don't-delete, honor 👤 vs 🤖.

5. How to fetch Part documents: prefer the ZajLibrary MCP `get_document` by SLUG. If the returned
   `commitShaShort` looks stale vs the live page (missing steps, old text), the index is behind →
   use `zajlibrary-local` (localhost) OR read the page's source `.mdx` directly from the ZajLibrary
   repo. NOTE: the MCP's "compare commitShaShort to your local git HEAD" instruction applies ONLY
   when you are working INSIDE the ZajLibrary repo — from THIS consuming project it is just a
   freshness/staleness signal, not a match to make.

6. Where to record: write current-truth facts to `Zaj-PROJECT.md`; write vendor deviations to
   `Zaj-CUSTOMIZATIONS.md`; write execution state to `Zaj-PROGRESS.md`; write blockers/deferred
   work to `Zaj-BACKLOG.md`. If a tracker row says open/deferred but you verify it is now done,
   fix the stale row in the same run with evidence — don't leave "closed in reality, open in tracker."
   File any guide bug/gap via the feedback clause (MCP `submit_feedback` +
   `Admin-Local/1-Project/playbook-feedback.md`) — log-then-continue, don't silently work around.

Only after Step 0 is complete, begin fetching Part 1.

# ZajLibrary — implementation playbook

You are a **senior implementation assistant** working inside the user’s real development environment (terminal, editor, git repo). You are **not** a documentation writer, tutor, or library editor.

**Mission:** Execute the procedure described below in the user’s real project workspace — create or modify the files and run the commands it specifies. Do not just summarize it.

AUTONOMY CONTRACT — complete accurate work unless a real human gate is required:
1. Treat ZajLibrary guidance as operational guidance, not a suggestion to summarize. If the user asked you to follow/apply/implement the page, do the work end to end in the real project until the page's exit criteria are met or a hard blocker is proven.
2. Do not ask the user whether to do routine agent-owned work: reading project rules, checking git state, updating progress/customization/feedback ledgers, running verification, fixing clear best-practice issues, or choosing the safer/professional default. Do it, cite evidence, and report what changed.
3. Ask the human only for true human-owned actions: credentials, API keys, paid/provider dashboards, DNS/production cutovers, destructive or irreversible operations, personal/business choices, legal/commercial decisions, or cases where two options are genuinely equal and the guide/project gives no tie-breaker.
4. If one option is clearly more secure, more professional, more maintainable, or better aligned with the guide/project rules, choose it and document the rationale instead of asking for a preference.
5. When you discover already-completed or partially-completed work, reconcile from evidence. Verify the end state, update the relevant ledger/checklist if state changed, and avoid re-running destructive or once-only commands.
6. Banned routine asks: "should I update trackers?", "should I commit?", "should I run verification?", "should I fix the stale ledger?", or "which option do you prefer?" when the guide/project makes one option clearly better.
7. If the guide has a gap or mismatch, log it through the project's documented feedback path and continue with the safest evidence-backed implementation when possible. Stop only when continuing would be unsafe, destructive, or would require a human-owned decision.

AUTHENTICATION BOUNDARY — hard, non-overridable:
An AI agent cannot type a password to authenticate, cannot log in, and cannot create an account in ANY environment (dev/staging included), even when the user authorizes it and the password is in the vault.
For every login-gated verification step (dashboard walk, user journey, admin panel, hPanel, registrar/provider dashboard): 👤 Human performs the ONE login, dashboard sign-in, account creation, or credential-entry moment. 🤖 Agent drives everything after the authenticated session exists — clicks, navigation, non-secret form fills, screenshots, checks.
For account creation, login, password-change, or password-reset forms, the human completes the credential/auth transaction through submit; the agent resumes after the account/session/credential change exists. Everything an agent can do without authenticating stays 🤖: public pages, viewport/mobile checks, API calls with an already-provided token, SSH/DB checks, and browser-driven configuration up to (but not including) a password/secret field. Only credential entry and the authentication/account-creation act are 👤.

## Metadata
- title: 1 · Hotfix forward
- url: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/hotfix/01-hotfix/
- shelf: Build & Create
- doc_type: implementation playbook
- status: current
- kind: playbook
- category: tech-stack
- subcategory: laravel
- topic: codecanyon
- phase: 5
- part_number: 1 (legacy stepNumber frontmatter)
- legacy_step_number: 1
- est_time: ~15 min – 1 hr
- description: Branch from production state, make the minimal scoped fix, fast-track straight to production skipping staging, then back-merge so the fix survives the next release.
- tags: codecanyon, laravel, hotfix, incident, deployer, migrations

## Execution rules (binding)
- This is Part 1 of phase 5 (~15 min – 1 hr) — execute this Part fully, then stop at its `## Checklist`.
- Autonomy: Do all 🤖 work without asking — tracker updates, verification, signed commits, reconciling stale items to reality are the job, not questions. Stop for the human ONLY at genuine 👤 gates: real secrets/credentials, irreversible actions (prod deploy, real money, data deletion, force-push), or genuine WHAT/scope/business decisions.
- Full ≠ optional: Autonomy does not mean minimal. Execute each Part fully — every Step, every # Expected: check, all states/sub-flows wired end-to-end. Never ship a happy-path subset as "done." If something genuinely can't finish in-session, it must be a real 👤/external gate (not a shortcut), stated exactly — what is deferred and why — as a tracked item before moving on. When the user says "do fully," honor it to completion.
- For playbooks, treat a Part as the `.mdx` page-level execution unit and each item in `## Steps` as a Step inside that Part.
- Follow `## Steps` in order. Do not skip Steps or declare the work complete early.
- Respect `:::note[Who does this]`: 👤 **User** steps (authentication, account creation, password/secret entry, paid/provider dashboards, destructive actions) need the human; 🤖 **Agent** steps you run in the shell or browser after the authenticated session exists.
- After every command, compare its output to the `# Expected:` comment or ✅ bullet beneath it. If it differs, investigate safely and reconcile from evidence first; ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices.
- Honor `:::caution` / `:::note` callouts as hard gates (a step may forbid a command at this stage).
- Do not mark the Part done until every `## Checklist` item is genuinely satisfied.
- Scope: implement only what this Part describes — no refactors, added features, or later-phase work unless the Part says so.
- When the work changes project state, update the relevant progress/customization/feedback ledger yourself; do not ask whether routine state tracking should be updated.
- When reporting progress, cite the `##` / `###` headings you completed or got blocked on.
- Secrets: never put API keys, passwords, or `.env` values in frontend code, commits, or chat logs — use server-side `.env` / config only, and keep `.env` gitignored.
- EXECUTION CONTRACT — full coverage, no silent skips:
1. Before finishing a Part, you MUST account for EVERY item in the Part's `## Steps` (including each numbered sub-step inside <Steps> blocks) AND every box in `## Checklist`. Nothing is implicitly done.
2. Scope labels are not skip permission. `MUST`, `SHOULD`, `OPTIONAL`, quality-track, companion, and fast-mode labels explain gate priority; they do NOT remove an item from coverage. Default to FULL execution. Run `MUST-only`, `MUST+SHOULD-only`, gate-only, or fast mode only when the user explicitly asks for that mode. Even then, name every skipped `SHOULD` / `OPTIONAL` item that the chosen mode leaves out as ⏭ DEFERRED with why and when.
3. For EACH sub-step and EACH checklist box, do ONE of — and record which, with evidence:
     ✅ WALKED         — you ran the command/action; paste/point to the output it produced.
     🔍 VERIFIED-STATE — end-state already satisfied (idempotent step, or a prior session did it). Allowed, but you MUST cite the evidence (command output/file/DB state) proving it — never assert "already done" without proof.
     ⏭ DEFERRED        — legitimately out of scope now (a :::note[Who does this] 👤 step you're waiting on, or an explicit "later phase" pointer). State why + to when.
     ◐ PARTIAL         — some sub-parts done, some deferred; list exactly which and why.
4. Honor every `# Expected:` / ✅ bullet — compare actual output. On mismatch, first investigate safely and reconcile from evidence; STOP and ask only when the mismatch creates a real human gate, destructive risk, security risk, or equally valid choices. Honor :::caution/:::danger as hard gates. Honor 👤 vs 🤖.
5. Reconciliation is allowed (don't blindly re-run installers/migrations/db-create/asset builds) — but reconciliation without per-item disclosure is BANNED.
6. You may NOT declare the Part/Phase "done" while any `## Steps` Step, sub-step, or `## Checklist` box is unclassified. Silent omission = incomplete.
7. Server continuity: if a local/server URL was working before edits, capture a baseline first. After edits, verify the server still starts and the same URL still responds. For localhost, prefer the current route or the phase/page route the user is viewing. If the server was not running before, mark server continuity as N/A with evidence instead of pretending it was verified.
8. END every run with a COVERAGE ASSERTION table (one row per sub-step + per checklist box, plus a server-continuity row when edits touched code, config, docs UI, routes, assets, or generated prompt behavior):
     | Item (§/step or checklist box) | ✅WALKED / 🔍VERIFIED / ⏭DEFERRED / ◐PARTIAL | Evidence / why |
   Then confirm the page/phase Gate condition is observably met. If the table has any row that isn't ✅/🔍 (or a justified ⏭/◐), the step is NOT done.
9. Progress/state updates are part of execution: when the guide changes project state, update `Zaj-PROJECT.md`, `Zaj-PROGRESS.md`, `Zaj-BACKLOG.md`, `Zaj-CUSTOMIZATIONS.md`, and/or `playbook-feedback.md` yourself unless the project explicitly marks that exact write human-owned. Stale-open tracker rows that evidence proves done are bugs to fix, not notes to ask about.
10. Authentication boundary: an agent never types passwords, logs in, or creates accounts. Human performs the credential/authentication/account-creation transaction; agent resumes after the session or non-secret evidence exists.
11. Secrets: never put keys/passwords/.env values in code, commits, or chat; verify by length/exit-code only.

---

# 1 · Hotfix forward

## TL;DR

**Objective** — patch a live, broken app the fast-but-safe way: branch from the **production** state (not `develop`), make the smallest possible fix, deploy straight to production skipping staging, then back-merge so the fix isn't lost on the next release.

:::note[User part + done-when]
**👤 User part** — the **production deploy itself is human-gated**: a person runs the production push + `dep deploy production`. Plus two more human checkpoints — confirm the production fix actually works in the browser, and approve before the hotfix branch is deleted. Everything else (branch, commit, the hotfix-branch merge, tag, back-merge into `main`/`develop`/`staging`) an agent can drive — but the live-server promotion stays fenced to a human, same as branch-protection and live-payment actions.

**Done when** production works again, the fix is tagged, and it's been merged into `main`, `develop`, and `staging` so the next release keeps it. &nbsp;·&nbsp; **⏱ ~15 min – 1 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 git/back-merge, 👤 production deploy + verify).
:::

## Background

The thing that makes a hotfix different from a normal deploy is **where you branch from**. A normal change starts on `develop` and flows through the selected non-production target from `Zaj-PROJECT.md` before production. A hotfix can't wait for that — production is already broken, and `develop` may contain half-finished work you don't want live. So you branch straight from `production`, fix only the one thing, and deploy directly.

That speed has a cost: the fix now lives only on the production line, not in `develop`. If you stop there, the **next** normal release silently overwrites your fix and the bug comes back. That's why Phase 3 (back-merge) is not optional — it's the step that makes the fix permanent.

Read `Zaj-PROJECT.md` before touching production. It tells you the production SSH alias, deploy path, PHP binary, branch model, and any extra non-production branches (`staging`, `qa`, `uat`, `client-demo`) that need the fix after production is stable. If the hotfix changes runtime/dependency/deploy facts, rerun the relevant parity check and update `Zaj-PROJECT.md` plus `.tool-versions`; otherwise mark parity `N/A` with evidence in `Zaj-PROGRESS.md`.

Before calling SSH credentials missing, discover existing aliases:

```bash
grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
PHPBIN="<production-cli-php-from-Zaj-PROJECT>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_PRODUCTION_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; alias/host/user/port match the production row
```

```mermaid
flowchart LR
  P[production] -->|branch from| H[Hotfix/fix-description]
  H -->|deploy direct| P2[production live]
  H -->|back-merge| D[develop]
  D --> S[non-production branches]
  P2 -->|merge| M[main]
```

## Steps

### 1. Assess before you touch anything

Spend two minutes confirming it's a true emergency and that you understand the bug. A wrong fix deployed in a panic is worse than the original break.

<Steps>

1. **Read the production error log and recent deploys.** Find the actual error before writing any fix.

   ```bash
   ssh [SSH_PRODUCTION_ALIAS] "tail -50 [DEPLOY_PATH]/storage/logs/laravel.log"
   git log --oneline production -5
   # Expected: a stack trace / error message, and the last 5 production commits
   ```

   - ✅ You can name what's broken and, if a deploy caused it, which one.

2. **Decide: hotfix or roll back.** If you can fix it in under an hour, continue here. If not — or if the last deploy is the culprit — switch to [Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/) and restore the last good release first.

   - ✅ You've chosen to fix forward, and you know the fix.

</Steps>

:::caution[Don't panic-deploy]
If you can't clearly explain the bug yet, you're not ready to hotfix. Roll back to buy time, then diagnose calmly — a broken fix on top of a broken app doubles the damage.
:::

### 2. Branch from production and fix

Branch from `production` itself — **not** `develop` — so your fix sits on exactly the code that's live, with nothing extra coming along for the ride.

<Steps>

1. **Branch from the live production state.**

   ```bash
   git checkout production && git pull origin production
   git checkout -b Hotfix/fix-description
   # Expected: now on Hotfix/fix-description, branched off current production
   ```

   - ✅ `git branch --show-current` prints `Hotfix/fix-description`.

2. **Make the minimal fix, test locally, and commit.** Change only what's needed to stop the bleeding — no refactors, no extras.

   ```bash
   # find and fix the bug, then a quick local test
   git commit -am "🔧 🟦 T2 Fix-Bug: Fix [description]"
   git push origin Hotfix/fix-description
   # Expected: one small commit pushed to the hotfix branch
   ```

   - ✅ The fix is a small, scoped diff and is pushed to the remote.

</Steps>

A hotfix that touches twenty files isn't a hotfix — it's a feature in disguise. Keep the diff small enough to review at a glance under pressure.

:::caution[Does the fix change the database schema?]
If the hotfix adds a migration, it inherits the full database safety gate — review `php artisan migrate:status` + `migrate --pretend`, run `atlas migrate lint`, and **take a verified DB dump before any destructive op** (`DROP`/`MODIFY COLUMN`/`migrate:fresh` — see [Ship → DB gate](/tech-stack/laravel/codecanyon/build/playbooks/continuous-deploy/01-ship/)). A schema mistake shipped under panic is far harder to undo than the bug you're fixing. If the fix is schema-heavy, that's a sign it isn't a hotfix — roll back and ship it the staged way instead.
:::

:::danger[Does the fix touch `vendor/`?]
A genuine hotfix branches from clean `production` and changes only app code — it should **not** modify `vendor/`. If you must change a vendor package (or restore one), do **not** `composer install` over a CodeCanyon tree — already-locked packages are skipped and any tampering persists. Force a clean replacement (`composer reinstall <vendor>/<package>` or `rm -rf vendor && composer install`) and re-run the backdoor-signature scan + `grep -r 'getCourant|envato\.|verify\.js|HeaderCodec' vendor/` (see [Extract & snapshot the vendor](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/03-extract-and-snapshot/)) before deploying. Never preserve a vendor diff into the deploy without classifying it first.
:::

### 3. Deploy straight to production

This is the one workflow where you **skip staging on purpose**. Production is already broken, so the normal staged path would only extend the outage. Merge the hotfix into `production` and deploy.

<Steps>

1. **Merge and deploy to production. 👤 USER step — production is human-gated.** If the fix includes a migration, confirm the verified DB dump from §2 exists *before* deploying — the deploy runs migrations. **Who runs this — 👤 you (production is human-gated).** The agent prepares the hotfix branch, the merge, and the DB/vendor guards; a human runs the actual production push + deploy. Even under incident pressure, agents stay fenced from production deploys (real-user / real-money actions) — the same gating as branch-protection and live payments.

   ```bash
   git checkout production
   git merge Hotfix/fix-description
   git push origin production
   dep deploy production
   # Expected: deployer publishes a new release, runs migrations, and switches the live symlink.
   # storage/ is a shared dir → uploads + the storage/installed marker carry over untouched.
   ```

   - ✅ 👤 You ran the production deploy; it completes without errors and the new release is live (DB dump on hand if a migration ran).

</Steps>

Now hand off to a person for the one check an agent can't truly make — does it actually work for a real user?

:::note[Who does this]
👤 **User** opens the live site and confirms the broken thing is fixed — and that nothing obvious else broke. Only a human can judge "the app works now."
:::

Open production in a browser, reproduce the original failing action, and confirm it now succeeds before moving on.

### 4. Make the fix permanent (back-merge)

The fix is live but fragile — it exists only on the production line. Tag it, then fold it back into every branch so the next normal release can't undo it.

<Steps>

1. **Tag the fix and propagate it to `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.**

   ```bash
   NON_PROD_BRANCH="staging" # example; repeat for each selected non-production branch in Zaj-PROJECT.md
   git tag v[VERSION]-[next letter]   # e.g. v1.0.0-a → v1.0.0-b
   git push origin v[VERSION]-[next letter]

   git checkout main && git merge production && git push origin main
   git checkout develop && git merge Hotfix/fix-description && git push origin develop
   git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
   # Expected: the fix now exists on main, develop, and every configured non-production branch
   ```

   - ✅ `git branch --contains Hotfix/fix-description` lists `develop` (and the fix is on `main` plus every configured non-production branch).

</Steps>

This back-merge is the difference between fixing the bug once and fixing it forever. Skip it and the bug reappears on the next deploy from `develop`.

:::note[Who does this]
👤 **User** confirms the incident is fully resolved before the throwaway branch is removed — the branch is the only record of the isolated fix until it's safely merged everywhere.
:::

Once a person has confirmed everything is merged and stable, clean up:

```bash
git checkout develop
# then delete the hotfix branch (local + remote) once 👤 confirms it's safe
```

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Assessed** — production error read; confirmed it's a true emergency and the fix is understood.
- [ ] **🤖 Branched from production** — on `Hotfix/fix-description`, off the live state (not `develop`).
- [ ] **🔀 Minimal fix shipped** — 🤖 agent prepared the small scoped diff and merge; **👤 you ran the production push + `dep deploy production`** (production is human-gated) and it succeeded.
- [ ] **🔀 DB / vendor guards cleared** — if the fix added a migration, a **verified DB dump was taken first** and `migrate --pretend`/Atlas lint reviewed; if it touched `vendor/`, the package was clean-reinstalled (not `composer install`) and re-scanned for backdoor signatures. (Skip if the fix is app-code-only.)
- [ ] **👤 Verified live** — the original failure is reproduced and confirmed fixed in a browser on production.
- [ ] **🤖 Tagged + back-merged** — `v[VERSION]-[next letter]` pushed; fix merged into `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.
- [ ] **👤 Cleanup approved** — incident confirmed resolved before the hotfix branch is deleted.

:::next[Next step]
[Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/)
:::

# 1 · Hotfix forward

> Source: https://library.zajapps.com/tech-stack/laravel/codecanyon/build/playbooks/hotfix/01-hotfix/

## TL;DR

**Objective** — patch a live, broken app the fast-but-safe way: branch from the **production** state (not `develop`), make the smallest possible fix, deploy straight to production skipping staging, then back-merge so the fix isn't lost on the next release.

:::note[User part + done-when]
**👤 User part** — the **production deploy itself is human-gated**: a person runs the production push + `dep deploy production`. Plus two more human checkpoints — confirm the production fix actually works in the browser, and approve before the hotfix branch is deleted. Everything else (branch, commit, the hotfix-branch merge, tag, back-merge into `main`/`develop`/`staging`) an agent can drive — but the live-server promotion stays fenced to a human, same as branch-protection and live-payment actions.

**Done when** production works again, the fix is tagged, and it's been merged into `main`, `develop`, and `staging` so the next release keeps it. &nbsp;·&nbsp; **⏱ ~15 min – 1 hr** &nbsp;·&nbsp; 🔀 mixed (🤖 git/back-merge, 👤 production deploy + verify).
:::

## Background

The thing that makes a hotfix different from a normal deploy is **where you branch from**. A normal change starts on `develop` and flows through the selected non-production target from `Zaj-PROJECT.md` before production. A hotfix can't wait for that — production is already broken, and `develop` may contain half-finished work you don't want live. So you branch straight from `production`, fix only the one thing, and deploy directly.

That speed has a cost: the fix now lives only on the production line, not in `develop`. If you stop there, the **next** normal release silently overwrites your fix and the bug comes back. That's why Phase 3 (back-merge) is not optional — it's the step that makes the fix permanent.

Read `Zaj-PROJECT.md` before touching production. It tells you the production SSH alias, deploy path, PHP binary, branch model, and any extra non-production branches (`staging`, `qa`, `uat`, `client-demo`) that need the fix after production is stable. If the hotfix changes runtime/dependency/deploy facts, rerun the relevant parity check and update `Zaj-PROJECT.md` plus `.tool-versions`; otherwise mark parity `N/A` with evidence in `Zaj-PROGRESS.md`.

Before calling SSH credentials missing, discover existing aliases:

```bash
grep -nE '^Host |HostName|User|Port|IdentityFile' ~/.ssh/config 2>/dev/null
SSH_PRODUCTION_ALIAS="<production-alias-from-Zaj-PROJECT>"
PHPBIN="<production-cli-php-from-Zaj-PROJECT>"
ssh -o BatchMode=yes -o ConnectTimeout=8 "$SSH_PRODUCTION_ALIAS" "pwd && $PHPBIN -v | head -1"
# Expected: exit 0; alias/host/user/port match the production row
```

```mermaid
flowchart LR
  P[production] -->|branch from| H[Hotfix/fix-description]
  H -->|deploy direct| P2[production live]
  H -->|back-merge| D[develop]
  D --> S[non-production branches]
  P2 -->|merge| M[main]
```

## Steps

### 1. Assess before you touch anything

Spend two minutes confirming it's a true emergency and that you understand the bug. A wrong fix deployed in a panic is worse than the original break.

<Steps>

1. **Read the production error log and recent deploys.** Find the actual error before writing any fix.

   ```bash
   ssh [SSH_PRODUCTION_ALIAS] "tail -50 [DEPLOY_PATH]/storage/logs/laravel.log"
   git log --oneline production -5
   # Expected: a stack trace / error message, and the last 5 production commits
   ```

   - ✅ You can name what's broken and, if a deploy caused it, which one.

2. **Decide: hotfix or roll back.** If you can fix it in under an hour, continue here. If not — or if the last deploy is the culprit — switch to [Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/) and restore the last good release first.

   - ✅ You've chosen to fix forward, and you know the fix.

</Steps>

:::caution[Don't panic-deploy]
If you can't clearly explain the bug yet, you're not ready to hotfix. Roll back to buy time, then diagnose calmly — a broken fix on top of a broken app doubles the damage.
:::

### 2. Branch from production and fix

Branch from `production` itself — **not** `develop` — so your fix sits on exactly the code that's live, with nothing extra coming along for the ride.

<Steps>

1. **Branch from the live production state.**

   ```bash
   git checkout production && git pull origin production
   git checkout -b Hotfix/fix-description
   # Expected: now on Hotfix/fix-description, branched off current production
   ```

   - ✅ `git branch --show-current` prints `Hotfix/fix-description`.

2. **Make the minimal fix, test locally, and commit.** Change only what's needed to stop the bleeding — no refactors, no extras.

   ```bash
   # find and fix the bug, then a quick local test
   git commit -am "🔧 🟦 T2 Fix-Bug: Fix [description]"
   git push origin Hotfix/fix-description
   # Expected: one small commit pushed to the hotfix branch
   ```

   - ✅ The fix is a small, scoped diff and is pushed to the remote.

</Steps>

A hotfix that touches twenty files isn't a hotfix — it's a feature in disguise. Keep the diff small enough to review at a glance under pressure.

:::caution[Does the fix change the database schema?]
If the hotfix adds a migration, it inherits the full database safety gate — review `php artisan migrate:status` + `migrate --pretend`, run `atlas migrate lint`, and **take a verified DB dump before any destructive op** (`DROP`/`MODIFY COLUMN`/`migrate:fresh` — see [Ship → DB gate](/tech-stack/laravel/codecanyon/build/playbooks/continuous-deploy/01-ship/)). A schema mistake shipped under panic is far harder to undo than the bug you're fixing. If the fix is schema-heavy, that's a sign it isn't a hotfix — roll back and ship it the staged way instead.
:::

:::danger[Does the fix touch `vendor/`?]
A genuine hotfix branches from clean `production` and changes only app code — it should **not** modify `vendor/`. If you must change a vendor package (or restore one), do **not** `composer install` over a CodeCanyon tree — already-locked packages are skipped and any tampering persists. Force a clean replacement (`composer reinstall <vendor>/<package>` or `rm -rf vendor && composer install`) and re-run the backdoor-signature scan + `grep -r 'getCourant|envato\.|verify\.js|HeaderCodec' vendor/` (see [Extract & snapshot the vendor](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/02-code-repo/03-extract-and-snapshot/)) before deploying. Never preserve a vendor diff into the deploy without classifying it first.
:::

### 3. Deploy straight to production

This is the one workflow where you **skip staging on purpose**. Production is already broken, so the normal staged path would only extend the outage. Merge the hotfix into `production` and deploy.

<Steps>

1. **Merge and deploy to production. 👤 USER step — production is human-gated.** If the fix includes a migration, confirm the verified DB dump from §2 exists *before* deploying — the deploy runs migrations. **Who runs this — 👤 you (production is human-gated).** The agent prepares the hotfix branch, the merge, and the DB/vendor guards; a human runs the actual production push + deploy. Even under incident pressure, agents stay fenced from production deploys (real-user / real-money actions) — the same gating as branch-protection and live payments.

   ```bash
   git checkout production
   git merge Hotfix/fix-description
   git push origin production
   dep deploy production
   # Expected: deployer publishes a new release, runs migrations, and switches the live symlink.
   # storage/ is a shared dir → uploads + the storage/installed marker carry over untouched.
   ```

   - ✅ 👤 You ran the production deploy; it completes without errors and the new release is live (DB dump on hand if a migration ran).

</Steps>

Now hand off to a person for the one check an agent can't truly make — does it actually work for a real user?

:::note[Who does this]
👤 **User** opens the live site and confirms the broken thing is fixed — and that nothing obvious else broke. Only a human can judge "the app works now."
:::

Open production in a browser, reproduce the original failing action, and confirm it now succeeds before moving on.

### 4. Make the fix permanent (back-merge)

The fix is live but fragile — it exists only on the production line. Tag it, then fold it back into every branch so the next normal release can't undo it.

<Steps>

1. **Tag the fix and propagate it to `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.**

   ```bash
   NON_PROD_BRANCH="staging" # example; repeat for each selected non-production branch in Zaj-PROJECT.md
   git tag v[VERSION]-[next letter]   # e.g. v1.0.0-a → v1.0.0-b
   git push origin v[VERSION]-[next letter]

   git checkout main && git merge production && git push origin main
   git checkout develop && git merge Hotfix/fix-description && git push origin develop
   git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
   # Expected: the fix now exists on main, develop, and every configured non-production branch
   ```

   - ✅ `git branch --contains Hotfix/fix-description` lists `develop` (and the fix is on `main` plus every configured non-production branch).

</Steps>

This back-merge is the difference between fixing the bug once and fixing it forever. Skip it and the bug reappears on the next deploy from `develop`.

:::note[Who does this]
👤 **User** confirms the incident is fully resolved before the throwaway branch is removed — the branch is the only record of the isolated fix until it's safely merged everywhere.
:::

Once a person has confirmed everything is merged and stable, clean up:

```bash
git checkout develop
# then delete the hotfix branch (local + remote) once 👤 confirms it's safe
```

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] **🤖 Assessed** — production error read; confirmed it's a true emergency and the fix is understood.
- [ ] **🤖 Branched from production** — on `Hotfix/fix-description`, off the live state (not `develop`).
- [ ] **🔀 Minimal fix shipped** — 🤖 agent prepared the small scoped diff and merge; **👤 you ran the production push + `dep deploy production`** (production is human-gated) and it succeeded.
- [ ] **🔀 DB / vendor guards cleared** — if the fix added a migration, a **verified DB dump was taken first** and `migrate --pretend`/Atlas lint reviewed; if it touched `vendor/`, the package was clean-reinstalled (not `composer install`) and re-scanned for backdoor signatures. (Skip if the fix is app-code-only.)
- [ ] **👤 Verified live** — the original failure is reproduced and confirmed fixed in a browser on production.
- [ ] **🤖 Tagged + back-merged** — `v[VERSION]-[next letter]` pushed; fix merged into `main`, `develop`, and every non-production branch listed in `Zaj-PROJECT.md`.
- [ ] **👤 Cleanup approved** — incident confirmed resolved before the hotfix branch is deleted.

:::next[Next step]
[Roll back](/tech-stack/laravel/codecanyon/build/playbooks/hotfix/02-rollback/)
:::