diff --git a/docs/guides/06-TEAM-USER-GUIDE.md b/docs/guides/06-TEAM-USER-GUIDE.md new file mode 100644 index 0000000..0b1c6e2 --- /dev/null +++ b/docs/guides/06-TEAM-USER-GUIDE.md @@ -0,0 +1,825 @@ +# Guide 06 — The SMOrchestra Engineering OS + +**Audience:** every SMOrchestra engineer + QA, Day 1 to Day 365. Pin it. Re-read every quarter. +**OS version:** smorch-dev **v1.6.0** + smorch-ops **v1.1.0** +**What this is:** the way we think about building, not the syntax of commands. Commands are appendix material. Judgment is the doc. +**What this is NOT:** a tutorial. There are 7 other guides for click-by-click instruction. This is the operating system manual — the philosophy + scenarios + decisions you internalize once and apply forever. +**Companion docs you'll need:** +- [05-PLUGIN-COMPLETE-GUIDE.md](05-PLUGIN-COMPLETE-GUIDE.md) — every command, every skill, every scenario (long reference) +- [04-SETUP-ENVIRONMENT.md](04-SETUP-ENVIRONMENT.md) — fresh-machine install +- [01-START-NEW-APP.md](01-START-NEW-APP.md) — zero-to-shippable scaffolding +- `~/.claude/CLAUDE.md` — founder's global rules. Sacred. Read before writing one line. + +--- + +## Part 1 — Why This OS Exists + +### 1.1 The thesis + +SMOrchestra ships engineering work the same way it sells its product: **signal-based, not relationship-based**. The same way we tell clients "relationship-based selling is a tax on growth," we tell ourselves: **tribal-knowledge engineering is a tax on shipping**. + +Tribal knowledge looks like: "ask Mamoun about this part," "we usually do it this way," "remember when X broke last quarter?" Every one of those phrases is a future incident waiting to happen. They cost weeks every time someone leaves or onboards. + +The OS replaces every "we usually" with a slash command + a validator + a gate. If a rule matters, it's mechanical. If it's mechanical, the next hire inherits it for free. + +### 1.2 What we optimize for (in priority order) + +1. **Customer trust** — we run paying customers' production. Drift, regressions, and silent failures are existential. Everything else is downstream of this. +2. **Compounding velocity** — the OS should make month 6 faster than month 1, not slower. We invest in scaffolds and validators because they pay back every PR forever. +3. **Honest calibration** — a system that scores its own work has to be brutally honest, or it's just theatre. Self-rounding is the failure mode L-001 was written for. +4. **MENA-first defaults** — Arabic RTL, mobile 375px, Fri/Sat weekend, AED/SAR/QAR/KWD currencies. These are the defaults; English-only is the exception that needs a CEO PR. +5. **Founder leverage** — Mamoun is the bottleneck for anything strategic. The OS exists so most days he isn't pinged for routine ops. He acts as CPO + lead architect; the OS handles GitHub admin, DB admin, n8n admin, server admin, drift, secrets, drift, deploy. + +If you ever find yourself doing work the OS could do, **fix the OS**, don't work around it. That's how it compounds. + +### 1.3 What the OS forbids by design + +- Tribal knowledge ("we usually do X") — encode it as a skill, a SOP, or a lesson, or delete it +- Untested manual fixes on servers ("just SSH in and...") — L-009 violation, drift detector will catch it +- Self-scoring rounded up ("close enough to 92...") — L-001 says don't. Fix the gap, don't round. +- Bundled refactors ("while I'm here let me clean up...") — one pattern, one PR. Big refactors get their own score. +- Anything that bypasses a gate without a PR documenting the bypass — the gate is the audit trail. Skipping = no trail. + +--- + +## Part 2 — The Mental Model + +You don't memorize 27 commands. You memorize **3 layers** and one **chain**. Everything else falls out. + +### 2.1 The 3-layer cognitive model + +``` +LAYER 1 — Commands (what you type) + /smorch-dev-start · /smo-dev-guide · /smo-plan · /smo-code · /smo-verify + /smo-score · /smo-bridge-gaps · /smo-simplify · /smo-handover · /smo-qa-run + /smo-ship · /smo-deploy · /smo-canary · /smo-document · /smo-cso + + smorch-ops: /smo-rollback · /smo-drift · /smo-health · /smo-incident · /smo-secrets + +LAYER 2 — SMOrchestra skills (what makes us SMO) + smo-scorer (5-hat rubric) · brd-traceability · handover-generator + qa-handover-scorer · arabic-rtl-checker · mena-mobile-check + elegance-pause · lessons-manager · cost-tracker · dev-guide-router · dev-start-bootstrap + +LAYER 3 — gstack + superpowers (the upstream craft) + superpowers: writing-plans · test-driven-development · systematic-debugging + · verification-before-completion · subagent-driven-development + · using-git-worktrees · requesting-code-review · receiving-code-review + · dispatching-parallel-agents · finishing-a-development-branch + gstack: autoplan · plan-eng-review · plan-ceo-review · plan-design-review + · investigate · simplify · codex · review · ultrareview · careful · guard + · ship · land-and-deploy · qa · qa-only · design-review · canary + · benchmark · browse · cso · retro · document-release · run +``` + +**The rule of layers:** you type L1. L1 calls L2 (SMO rules). L2 delegates craft to L3 (gstack/superpowers). You never edit L3 in normal work. L2 stays small (frozen at 11 skills); the test rig + SOP-36 enforce this. + +When a question comes up like *"should this go in a skill?"* — the answer is: +- Is it SMO-specific (5-hat scoring, MENA gating, BRD trace, handover)? → L2 +- Is it general craft (TDD, planning, debugging, deploying)? → L3, don't reimplement, delegate +- Is it a verb you'll type? → L1, thin wrapper, points at L2 + L3 + +### 2.2 The chain as a forcing function + +The chain isn't a workflow. It's a **forcing function** that makes shortcuts mechanically impossible. + +``` +/smorch-dev-start → refuses to let you work on a broken environment +/smo-plan → forces plan-mode discipline (Boris #1) before code +/smo-worktree → forces isolated workspace (clean blast radius) +/smo-code → forces TDD (red→green→blue), forces /smo-verify before commit +/smo-verify → forces live verification — happy + risk_surfaces failures + edge +/smo-score → forces 5-hat self-scoring with auto-caps (no rounding up) +/smo-bridge-gaps → forces fix-the-weakest-hat-first (not the easiest one) +/smo-simplify → forces code-quality fixes when Eng Q4/Q5 drag (auto) +/smo-handover → forces structured QA brief with risk disclosure +/smo-qa-handover-score → forces QA to grade the brief BEFORE running QA +/smo-qa-run → forces 4-scenario coverage + MENA + axe + rollback drill +/smo-review-pr → forces external adversarial review (fresh reviewer, no session history) +/smo-ship → forces 6 parallel gates + build/test/audit, ALL must pass +/smo-document → forces docs to match shipped reality (auto, post-merge) +/smo-deploy → forces drift check pre + post, health check, log +/smo-canary → forces 30-min post-deploy watch, auto-rollback on breach +/smo-cso → forces nightly security audit + monthly deep scan +``` + +Each step is a forcing function. Skip one and you've smuggled a quality regression into shipped code. The chain is the gate; you don't bypass it, you fix what's blocking you. + +### 2.3 The verb boundaries + +Words matter. SOP-14 lists them; violate them and you've created confusion: + +| Verb | Means | Doesn't mean | +|---|---|---| +| `ship` | Merge PR + tag release. Local → GitHub. | NOT deploy. | +| `deploy` | SSH + pm2 reload / docker up. GitHub → server. | NOT merge. | +| `rollback` | Revert deploy + restart. Server-side recovery. | NOT git revert. | +| `triage` | Live diagnostic. Problem still happening. | NOT post-mortem. | +| `incident` | Post-mortem write-up. After resolution. | NOT diagnostic. | +| `score` | Rubric scoring. Review IS scoring. | NOT a separate review step. | +| `handover` | Dev → QA contract document. | NOT a deployment artifact. | +| `verify` | Run the live app, exercise change in real env. | NOT unit tests. | + +If you mix these up in a PR description, a Slack message, or a runbook, you'll cost someone half a day of confusion. Be precise. + +--- + +## Part 3 — Constraints You Must Internalize + +These are not opinions. They are the rules that already cost real money or time. Learn them on Day 1; live them forever. + +### 3.1 RULE 0 — money (the most important one) + +**No paid resource is created without two explicit confirmations from Mamoun.** + +The trigger was a $15-30 Contabo V92 incident on 2026-04-26: I assumed Contabo billed hourly (it bills monthly-minimum). Cancelling after 5 minutes still charged the full month. + +When the OS encounters anything paid (cloud instance, domain, SaaS subscription, paid API call beyond the user's existing subscriptions), it MUST: +1. Show a red 💸 SPEND APPROVAL REQUIRED 💸 block +2. Name the billing model explicitly: hourly-prorated / monthly-minimum / annual-prepaid / per-call / one-time +3. Ask for "yes spend" — twice, in writing, in the same conversation +4. Refuse to proceed on implicit approval, on "go ahead," on "proceed" + +Read `~/.claude/CLAUDE.md` § 🚨 MONEY GUARDRAIL end to end. Re-read it monthly. The default assumption when unsure is: **monthly-minimum, full month billed**. + +Probing a paid CREATE endpoint to "see what's available" counts as spending. Use read-only catalog endpoints or ask. + +### 3.2 The 9 active global lessons + +Loaded at every SessionStart via the hook. You should know them by L-number on Day 30. + +| L | What | Last triggered | +|---|---|---| +| L-001 | Back up `.env.local` before any server rebuild | 2026-04-21 | +| L-002 | Verify canonical state before declaring rollout complete | 2026-04-21 | +| L-003 | Apps live in `/opt/apps/`, not `/root/` | 2026-04-21 | +| L-004 | docker-compose apps ≠ PM2 apps (don't conflate) | 2026-04-21 | +| L-005 | Port conflict: system nginx vs compose nginx | 2026-04-21 | +| L-006 | Port ghosts survive docker restart | 2026-04-21 | +| L-007 | "Already restored" needs evidence — not assertions | 2026-04-21 | +| L-008 | Plugin commands/skills auto-discover — no arrays in plugin.json | 2026-04-20 | +| L-009 | GitHub is single source of truth — commit AND push every work unit | 2026-04-21 | + +Each lesson has a `Why:` and a `How to apply:`. Memorize the trigger; apply the rule. + +### 3.3 Escalation gates — when to involve Mamoun + +He's CPO + lead architect, and he wants the OS to absorb routine ops. So don't ping him on standard ops. **Do ping him on these:** + +- Anything in `auth/`, `payments/`, `migrations/`, `pii/`, `secrets/` — these are pre-declared risk surfaces +- Deploys to `smo-prod` or `eo-prod` (production servers) +- Force-push, hard reset, branch delete on any repo +- Cross-repo edits that touch someone else's in-flight work +- Anything paid (RULE 0) +- SEV1 incidents (revenue-critical outage, data loss, security breach) — immediate +- SEV2 incidents within 30 min +- Flipping `.smorch/project.json:qa.rollback_drill` from `required` to `optional` (CEO policy review) +- Flipping `.smorch/project.json:locale` from `ar-MENA` to `en-US` (CEO policy review) + +Everything else: act. Then summarize back in one line. That's the doctrine. + +### 3.4 Branch model (SOP-20) + +- `main` = production. Protected. Reflects what's deployed. You never develop on local `main`. L-014 trip-wire — `/smorch-dev-start` will go RED if you commit on main. +- `dev` = active. The default branch for new work. PRs target dev. +- `feat/{slug}` / `fix/{slug}` / `hotfix/{slug}` = feature branches off dev. + +Release path: `feat/* → dev (PR + merge)`. Promotion: `dev → main (release PR + Mamoun approval)`. Hotfix path: `hotfix/* → main directly, then cherry-pick to dev`. + +### 3.5 Local → GitHub → server (L-009) + +The single source of truth is GitHub. Always. + +- Edit locally +- Commit + push (every meaningful work unit, end of every session) +- Server pulls from GitHub via cron OR via `/smo-deploy` SSH + +If you SSH into a server and edit `app.js` directly because "it's just a one-line fix" — the drift detector catches it within an hour. The next deploy will auto-rollback because git HEAD ≠ server HEAD. You'll spend half a day cleaning up. Don't. + +### 3.6 Codex doctrine (SOP-11) + +- **Default: Claude Code** for architecture, planning, review, scoring, handovers, SOPs, CLAUDE.md work, all primary writing +- **Codex: gated** for high-volume mechanical refactors (1000+ i18n strings, log parsing at scale, synthetic test data) — requires Mamoun approval + audit row in `docs/codex-audit.csv` +- **Codex-as-reviewer: always allowed** for `/smo-review-pr` second-opinion (Codex never writes the shipped code, only critiques it) + +If you used Codex without an audit row, `/smo-score` Engineering Q5 caps at 7. + +--- + +## Part 4 — The 12 Scenarios + +This is the bulk of the guide. Each scenario gives you: the **situation**, the **temptation** (the wrong move that feels right), the **right path** (the OS answer), the **rule** that codifies why, and **what evidence proves** you did it right. + +Internalize these and you'll make the right call 95% of the time. The other 5% — ask Mamoun. + +--- + +### Scenario 1 — Your first day at SMOrchestra + +**Situation:** You've been hired (engineer or QA). You have a Mac (or Windows). You have a GitHub invite. You have nothing else. + +**Temptation:** Open an existing repo, poke around, get the "feel" of the codebase first. + +**Right path:** Install before you read. +1. Run the install one-liner for your role (`install/eng-desktop.sh` or `install/qa-machine.ps1`). It sets up node, gh, Claude Code, both plugins, gstack, superpowers, sync cron, hooks, `~/.claude/{CLAUDE.md, lessons.md, settings.json}`. +2. `gh auth login`. Verify with `gh repo list SMOrchestra-ai --limit 3`. +3. `tailscale up` (Mamoun adds you to the mesh). Verify with `ssh root@100.99.145.22` (eo-dev) — should connect. +4. `/smorch-dev-start --quiet` from your home dir → expect GREEN. If RED, run `--fix`; the auto-heal handles 90% of Day-1 issues. +5. THEN read, in order: this guide, `~/.claude/CLAUDE.md`, [SOP-13](../../../smorch-brain/sops/SOP-13-Lana-Handover-Protocol.md), [SOP-14](../../../smorch-brain/sops/SOP-14-Plugin-Workflow.md), [SOP-36](../../../smorch-brain/sops/SOP-36-L3-Cascade.md), the 9 lessons in `~/.claude/lessons.md`. + +**Rule:** L-007 — verify state with evidence before declaring readiness. A working `/smorch-dev-start` GREEN is your evidence the machine is ready. Reading first without verifying is how Day 1 becomes Day 3. + +**Evidence:** A screenshot of `/smorch-dev-start` GREEN, sent in your Day-1 thread. Doubles as your machine-ready confirmation to Mamoun. + +--- + +### Scenario 2 — Mamoun assigns you a new feature in a new project + +**Situation:** Mamoun says: "Build a UAE legal-translation Arabic→English assistant. MENA ICP. SalesMfast adjacent. Solo for now, Lana will QA." + +**Temptation:** Start coding. You have an idea. `git init`, scaffold a Next.js app, start writing. + +**Right path:** Treat the first 30 minutes as scaffold + alignment work, not coding work. +1. **Confirm scope verbally with Mamoun** in 3 questions: who's the ICP precisely? What's the MVP (1-AC version)? What's out of scope? +2. `gh repo create SMOrchestra-ai/{name} --private` + topic tags + create `dev` branch + clone to `~/Desktop/repo-workspace/smo/{name}/`. +3. Scaffold the mandatory file structure (Section 7 has the tree). 6 docs/ subfolders mandatory + 7 new v1.6 subfolders strongly recommended. +4. Write `architecture/brd.md` with: Problem, ICP, MVP scope, 3-5 ACs labeled `AC-1.1` through `AC-N.N`, OOS list, success metric, deps. ~80 lines. +5. Write `.smorch/project.json` filling: `project`, `stack`, `locale` (default `ar-MENA`), `has_ui` (true if Next.js), `risk_surfaces[]` (`auth` if there's login, etc.), `deploy.target`, `qa.rollback_drill`. +6. Write project `CLAUDE.md` — 40-80 lines, Boris-shaped: Stack, Non-negotiable rules, Command chain, Ship gates, Env vars, Deploy, Rollback SLA, Unique rules. +7. **NOW** `/smorch-dev-start` → should be GREEN with Layer 4 input-readiness ≥70 (the BRD is the thing that lifts it). +8. **NOW** `/smo-plan AC-1.1` — and code follows. + +**Rule:** Boris discipline (`~/.claude/CLAUDE.md` 2-file framework) — CLAUDE.md + BRD are the source of truth. Everything downstream is derived. Skipping = no AC to trace, no rule for `/smo-score` to enforce, no rollback contract for `/smo-qa-run` to drill. + +**Evidence:** `/smorch-dev-start` GREEN + `architecture/brd.md` with ≥3 ACs + `.smorch/project.json` validating against the canonical template. The PR that scaffolds these files IS the first PR. Score it. (`/smo-score --quick` is enough — there's no production code yet.) + +--- + +### Scenario 3 — Mamoun assigns you a feature in an EXISTING repo + +**Situation:** "Add a Hijri calendar toggle to EO-MENA. Should ship by next sprint. Lana will QA." + +**Temptation:** `git pull`, `git checkout -b feat/hijri-toggle`, start coding. + +**Right path:** Orient before executing. 5 minutes here saves 5 hours later. +1. `cd ~/Desktop/repo-workspace/eo/eo-mena && git checkout dev && git pull --ff-only` +2. `/smorch-dev-start` → note Layer 4 input-readiness. If <70, the repo's docs have rotted. Don't add features to a rotting repo silently — tell Mamoun, fix docs as part of the PR. +3. Read in order: `CLAUDE.md` (project-specific rules), `architecture/brd.md` (find the AC this maps to, OR plan to add a new `AC-N.N`), `.claude/lessons.md` (past failures on this specific project). +4. `/smo-dev-guide next` — reads `docs/qa-scores/`, `docs/handovers/`, git/PR state, recommends your one next command in context. +5. `git log -10 -- src/lib/dateFormat.ts` — what else changed in the area you're about to touch? If 3+ recent PRs in the same module, elevated regression risk. +6. Now `/smo-plan AC-N.N`. + +**Rule:** L-002 — verify canonical state before declaring readiness. The repo's input-readiness score IS that verification. Don't add to a rotting foundation. + +**Evidence:** A `docs/plans/{feature}.md` (auto-written by `/smo-plan`) that references the existing BRD AC + the 3 recent PRs in the area + the locale gating (ar-MENA → MENA checks will apply). + +--- + +### Scenario 4 — A customer reports a bug, you need to fix it + +**Situation:** Lana found a bug in EO-MENA: Arabic dates render Gregorian on the dashboard. SEV3 (annoying, not blocking transactions). Repro: load /dashboard with `locale=ar-AE`, observe header. + +**Temptation:** Open the file, find the `new Date().toLocaleString()` call, add `'ar-AE'` as the first arg, push, done. 5 minutes. + +**Right path:** Triage with discipline, even on small bugs. +1. `/smo-triage "Arabic dates rendering Gregorian on dashboard"` — invokes `gstack:investigate` + `superpowers:systematic-debugging`. Forms ≤3 hypotheses, ranks by likelihood, gathers evidence (logs, git blame, recent PRs, `/smo-drift` check). Confirms root cause before any fix. +2. Branch from dev: `git checkout dev && git pull --ff-only && git checkout -b fix/SMO-NNN-arabic-date-formatter` +3. **Write the failing test FIRST** — `tests/lib/dateFormat.test.ts` with `@AC-3.4` tag, covering: Arabic locale → correct calendar, empty input → returns "—" not crash, invalid date → throws `DateFormatError` not silent NaN, Friday/Saturday weekend display. +4. Run test → RED. +5. Fix `dateFormat.ts`: pass `locale: 'ar-AE'` + `calendar: 'gregory'` + Latin numerals (UAE government convention). +6. Run test → GREEN. Run full suite → all GREEN. +7. `/smo-score --quick` (or `--full` if the fix touched more than expected). Auto-invokes `/smo-verify` before commit per v1.6 wiring. +8. `/smo-handover` → fill scenarios + risk disclosure (this PR also touches `src/lib/i18n/numerals.ts` — flag it). +9. Lana: `/smo-qa-handover-score` → `/smo-qa-run`. PASS expected. +10. `/smo-ship --patch` → `/smo-deploy --target staging` → `/smo-canary` (auto, 30 min). Then promotion PR dev → main → `/smo-deploy --target production`. + +**Rule:** L-EO-MENA-011 (escaped bugs) — every bug ships a regression test. Without the test, the fix is half. The test prevents the next dev from re-introducing the same bug 6 months from now. + +**Evidence:** The regression test commits BEFORE the fix commit. The diff shows test-first discipline. `docs/qa/{date}-PR-{n}.md` PASS includes the new test in the scenario list. + +**Anti-pattern to avoid:** "Just patch it" without the test. The fix works today; the bug returns in 4 months because no test guards it. That's how features develop a regression rhythm. + +--- + +### Scenario 5 — Hotfix at 11pm Dubai time (SEV2) + +**Situation:** Telegram pings: production EO-MENA is returning 500s on `/api/draft`. It's 11pm. Mamoun is asleep but he's the on-call. + +**Temptation 1:** Wait until morning. (No — SEV2 = 30-min response.) +**Temptation 2:** SSH into eo-prod, edit the file, restart pm2. Done in 10 min. (No — L-009 violation; drift detector will auto-rollback within the hour.) + +**Right path:** Hotfix path bypasses the full chain BUT preserves the must-have gates. +1. `/smo-triage "EO-MENA /api/draft returning 500 in prod"` — get the root cause first. Don't guess. +2. **Branch from `main`** (not dev) for production hotfix: `git checkout main && git pull --ff-only && git checkout -b hotfix/SMO-NNN-draft-500` +3. Write failing regression test that reproduces the 500. Run → RED. +4. Minimal code change. Run → GREEN. Full suite → GREEN. +5. `/smo-score --quick` (2 min — Product + Engineering only). +6. **For SEV2, full handover still required, just expedited.** Lana scores fast, runs `/smo-qa-run --env staging` on the staging deploy. +7. `/smo-ship --patch` → `/smo-deploy --target production` → `/smo-canary --auto` (30 min watch with auto-rollback armed). +8. **Backport to dev IMMEDIATELY:** `git checkout dev && git pull --ff-only && git cherry-pick {hotfix-sha} && git push origin dev`. Don't leave overnight. +9. **Write the post-mortem within 48 hours:** `/smo-incident SEV2 draft-500-rate-limit-bypass` — fills the SOP-10 template from triage data. + +**Rule:** SEV2 = mitigation within 30 min, post-mortem within 48h. Hotfix discipline preserves the **regression test** + **score** + **handover** + **canary** even when bypassing the full chain. + +**Evidence:** PR merged to main with: regression test, score report, handover brief, QA pass, canary clean, post-mortem at `docs/incidents/{date}-SEV2-{slug}.md`, cherry-pick commit visible on dev branch. + +**Anti-pattern:** Bypassing the regression test "because we're in a hurry." The 5 minutes you save now costs you the same bug recurring in 3 months when memory has faded. + +--- + +### Scenario 6 — Your `/smo-score` returns 78 (REJECTED, <85) + +**Situation:** You ran `/smo-score --full`. Composite came back 78. Two hats below 8.5 floor. + +**Temptation:** Look for individual question scores to lawyer up against. "Q4 is too strict; surely my code is better than that." + +**Right path:** The rubric is descriptive, not aspirational. 78 means the PR has structural issues — not polish issues. +1. Read the dragging hat first. If Product is below 8.5, you probably have a BRD/scope problem — feature doesn't match ACs or scope crept. +2. If Engineering is below 8.5, you have a tests/types/error-handling/elegance problem — usually multiple, compounding. +3. If QA is below 8.5, you didn't run the code in a real environment, OR you don't have evidence in the PR description. +4. **DO NOT** run `/smo-bridge-gaps` on a <85 score. Bridge-gaps is for 85-91 (small lift). <85 means structural rework — go back to `/smo-plan` or `/smo-code`. +5. Fix the structural issue. Re-score. If 85-91, then `/smo-bridge-gaps`. If still <85, the problem is bigger than the PR — talk to Mamoun. + +**Rule:** L-001 (from eo-microsaas-dev) — *don't self-score immediately after building*. Take a coffee break before scoring. The rubric is honest; you should be too. + +**Evidence:** `docs/qa-scores/{date}-{time}.md` showing the REJECTED verdict + the specific dragging questions + the action you took (replan or rewrite). The trend.csv row should show the score climbing in the next iteration. + +**Anti-pattern:** "78 is close to 92, let me just `--no-block` past it." Your future self ships a 78 to Lana, gets the handover sent back at 60, has to redo it anyway, plus pays the reputation cost. Don't. + +--- + +### Scenario 7 — Your `/smo-score` returns 88 (BRIDGE-GAPS) + +**Situation:** Composite 88. One hat at 8.0 (the dragger). You're 4 points from shipping. + +**Temptation:** Look at the question with the lowest score and try to game it. "If I just add one more comment to satisfy Architecture Q8..." + +**Right path:** Trust the v1.6 auto-composition. +1. `/smo-bridge-gaps` — reads the latest score, identifies the lowest hat, routes to the matching L3 review skill: + - Product → `gstack:plan-ceo-review` (rethink scope) + - Architecture → `gstack:plan-eng-review` (architecture pass) + - Engineering → `superpowers:requesting-code-review` + **`/smo-simplify --auto` if Q4 (code quality) or Q5 (elegance) drag** + - UX → `gstack:plan-design-review` + - QA → `gstack:qa` extended coverage +2. The review surfaces specific gaps as **AUTO** (apply now), **REVIEW** (human decision), **DEFER** (follow-up issue). +3. AUTO fixes apply immediately. Look at the diff — if you disagree with one, revert it + document why in the PR. +4. Address REVIEW items. +5. Re-score. Expect 92+ if you addressed both AUTO and REVIEW. +6. If after 2 bridge-gaps loops you're still <92 → escalate to `/smo-plan` rework. Don't loop forever. + +**Rule:** Bridge-gaps is the SOP-02 honest-improvement path. It exists because 85-91 PRs are common and the diff between 88 and 92 is usually 2-3 specific, fixable gaps — not a rewrite. + +**Evidence:** `docs/qa-scores/{date}-{time}.md` showing 88 → bridge-gaps invocation → re-score 92+. The diff shows the specific AUTO fixes the reviewer applied. The PR description notes which REVIEW items you took (or deferred + why). + +**Anti-pattern:** Rounding up. If `/smo-simplify` applied AUTO fixes and re-score is 91.5, your composite is 91.5. Don't write "92" in the report. Run it again with real fixes. + +--- + +### Scenario 8 — Lana sends back your handover at 65 + +**Situation:** You filed `/smo-handover --notify`. Lana ran `/smo-qa-handover-score`. Score: 65. Verdict: SEND BACK. + +**Temptation:** Get defensive. "She's being too strict. The PR is clear." + +**Right path:** The 5 dimensions are non-negotiable. +1. Read her annotation file at `docs/handovers/{date}-PR-{n}-qa-score.md`. She lists which dimensions dragged and why. +2. The dimension Lana sends back most often: **Risk Disclosure (Section 4)**. Vague risk sections ("no known risks") consistently score 6-7. Specific risks ("this PR touches /lib/auth/session.ts — regression risk on login flow") score 9-10. +3. Other common gaps: + - Stub placeholders left in Section 2 scenarios (`{stub — replace with real steps}`) + - Rollback command absent or stale + - No staging URL + - Test account creds path missing +4. Fix every item in her list. Don't compensate, don't argue. The brief is the contract; you have to satisfy the contract. +5. `/smo-handover --validate` to confirm no stubs remain + all sections substantive. +6. `/smo-handover --notify` to ping her again. + +**Rule:** SOP-13 — handover is dev → QA contract. Lana QA's the PR against what the brief says. A weak brief = weak QA. Sending it back is the system working, not a personal slight. + +**Evidence:** Updated handover file with all items addressed. New `/smo-qa-handover-score` returns ≥80. Lana proceeds to `/smo-qa-run`. + +**Anti-pattern:** "Just verbally tell her the missing context." That breaks the contract. The brief IS the documentation. If it's not in the brief, it's not documented. Update the brief. + +--- + +### Scenario 9 — `/smo-canary` auto-rolled back your deploy 20 min after `/smo-ship` + +**Situation:** You ran `/smo-ship` → `/smo-deploy --target production`. Both succeeded. Telegram pings 20 min later: "🔴 eo-mena v1.4.2 canary BREACH — LCP regressed 22% on /draft, auto-rollback triggered → v1.4.1 restored, SEV2 stub created at `docs/incidents/`." + +**Temptation 1:** Disable canary on the next deploy ("it's too aggressive"). NO. +**Temptation 2:** Manually re-deploy without changes to "see if it sticks." NO — same regression, just delayed by 30 min. + +**Right path:** The canary did its job. Diagnose the regression. +1. Read the canary report at `docs/canary/{date}-v1.4.2.md`. It names the breach (LCP +22% on /draft). +2. Read the screenshot the canary captured. +3. Look at the diff between v1.4.1 (rolled-back-to) and v1.4.2 (rolled-back-from). Specifically the /draft route or its dependencies. +4. The likely culprit on a 22% LCP regression: a new synchronous fetch, a new large bundle import, missing memoization, or N+1 queries. +5. `/smo-triage "v1.4.2 /draft LCP +22%"` — diagnose root cause. +6. Fix. Add a `/smo-benchmark --update-baseline` step if the regression was intentional (e.g., a feature that genuinely needs more compute) — document why in the PR. +7. Re-score. Re-ship. Re-deploy. + +**Rule:** v1.6 auto-composition exists to catch what your `/smo-verify` couldn't. /smo-verify exercises the change in a dev environment; canary watches it under real production load. They're complementary, not redundant. + +**Evidence:** `docs/canary/{date}-v1.4.2.md` shows the breach. `docs/incidents/{date}-SEV2-canary-breach-{slug}.md` documents triage + fix. The next deploy's canary report shows GREEN. + +**Anti-pattern:** `/smo-deploy --no-canary` to bypass. You've removed the safety net while the underlying perf bug is still there. Customers find it instead of canary. + +--- + +### Scenario 10 — You're tempted to skip `/smo-verify` because the test is flaky + +**Situation:** `/smo-code` finished the green TDD step. `/smo-verify --auto` runs. It fails: "missing bearer → 500 (expected: 401)." You run the test locally — passes. You run it twice more — passes both times. + +**Temptation:** `/smo-verify --no-block` to push through. The test must be flaky. + +**Right path:** The test is exercising a different code path than your unit test thinks it is. +1. Read the `/smo-verify` evidence file at `docs/verifications/{date}-{branch}.md`. It captures the actual request → actual response → expected response. +2. `gstack:verify` runs against a REAL environment (dev server up, real auth middleware, real DB). Your unit test stubs auth. So a "flaky" failure here is probably a real production behavior your unit test doesn't catch. +3. Diagnose: what is `/api/auth/session` returning when the bearer is missing? Likely a 500 because someone removed the auth guard, or there's an unhandled exception in the middleware path. +4. Fix the actual issue. Re-run `/smo-verify` — should now return 401. +5. **Add a NEW unit test** that exercises the missing-bearer path explicitly. The next regression won't escape this time. + +**Rule:** `~/.claude/CLAUDE.md` § QA-DISCIPLINE — *exercise failure paths, not just happy paths*. This rule was captured after 4 escaped bugs to Lana in 24h on 2026-04-28, all preventable. /smo-verify is the mechanical enforcement. + +**Evidence:** The PR has 2 commits: (a) the original feature commit with the bug, (b) the fix commit with the failure-path unit test. The verification evidence file is referenced in the PR description. + +**Anti-pattern:** `--no-block`. You've shipped a production 500 to your customers because you didn't trust your own validator. The validator was right. + +--- + +### Scenario 11 — You're QA, dev claims "that's out of scope" + +**Situation:** You ran `/smo-qa-run`. Scenario 3 (error state) failed: app hangs for 30s then crashes when Claude API is unreachable. You write FAIL in the QA report. Dev replies: "That's out of scope — the Claude API integration was just bridged in this PR, full error handling is a follow-up." + +**Temptation:** Accept the dev's framing. Update QA to PASS. Move on. + +**Right path:** Check the handover brief's Section 4 (Risk Disclosure). +- If the dev flagged "Claude API error path is untested in this PR — follow-up SMO-NNN" in Section 4 → he was right; it's out of scope; mark QA PASS WITH NOTES referencing the follow-up. +- If Section 4 said "no known risks" or didn't mention the Claude API error path → it's a true fail; dev fixes it before ship. + +**Rule:** The handover brief is the contract. If it's not flagged as untested, it's expected to work. Lana's signing rule (`/smo-qa-run` workflow): scope arguments only count if pre-declared. + +**Evidence:** QA report links to the relevant Section 4 line of the handover. PASS WITH NOTES references the follow-up ticket; FAIL references the missing risk disclosure. + +**Anti-pattern:** "I'll just verbally agree the dev was right." That sets a precedent that risk disclosure doesn't matter. In 3 PRs you'll be QA-ing against undocumented scope. + +--- + +### Scenario 12 — You inherit a legacy repo with no `.smorch/` overlay + +**Situation:** Mamoun assigns you to fix a bug in `signal-sales-engine`. You `cd` in. `/smorch-dev-start` shows: Layer 3 RED — no `.smorch/project.json`. Layer 4 input-readiness 56. + +**Temptation:** "I'll just fix the bug, add the overlay later." The bug is small; the overlay is "infra work." + +**Right path:** Don't add to a foundation you haven't repaired. +1. Tell Mamoun: "SSE has no `.smorch/` overlay + input-readiness 56. Adding the overlay is a 30-min PR; should I do that first?" +2. He'll say yes (always — drift compounds; he'd rather pay 30 min now than 5 hours of confused PRs later). +3. Write a separate PR titled `chore: bootstrap .smorch overlay for signal-sales-engine`. Copy the template, fill the fields per the project's actual deploy target and stack, score it (use the plugin-meta override if applicable, otherwise the standard rubric), ship it. +4. Now `/smorch-dev-start` Layer 4 ≥ 70. Now you can do the bug fix in a clean second PR. + +**Rule:** L-002 — verify canonical state before declaring readiness. Adding features to a repo without an overlay is the engineering equivalent of building on sand. + +**Evidence:** Two PRs: (1) overlay bootstrap (small, fast), (2) the actual bug fix on the now-clean foundation. The bug fix PR's `/smo-score` will be ~5 points higher because the overlay enables proper hat scoring. + +**Anti-pattern:** Bundle "while I'm here let me add the overlay" into the bug fix PR. Now the PR is doing two things — Lana has to QA both, the diff is confusing, the score is muddled. + +--- + +## Part 5 — Decision Frameworks + +The OS resolves most decisions for you mechanically. These are the few that need human judgment. + +### 5.1 Should I `/smo-bridge-gaps` or replan? + +| Composite | Hat floor | Action | +|---|---|---| +| ≥92 | ≥8.5 every hat | Ship — `/smo-handover` | +| 85-91 | ≥8.5 every hat | `/smo-bridge-gaps` — lift to 92 | +| 85-91 | <8.5 any hat | `/smo-bridge-gaps` targeting that hat first | +| 80-84 | any | `/smo-bridge-gaps` aggressively; if 2 loops don't lift to 85+, replan | +| <80 | any | Replan — `/smo-plan` rework. Bridge-gaps won't save this. | + +### 5.2 `/smo-ship --patch` vs `--minor` vs `--major` + +| Change type | Bump | +|---|---| +| Bug fix, doc update, config tweak, refactor with no API change | `--patch` (default) | +| New feature, new endpoint, new behavior, new env var | `--minor` | +| Breaking API change, schema migration requiring downtime, removed feature | `--major` | + +A `--major` bump REQUIRES: ADR documenting the break + migration script + rollback procedure + Mamoun PR approval. + +### 5.3 `/smo-deploy --target` order + +Always: `staging` first, then `production`. No exceptions for paid features. Production deploys require: +- Last `/smo-deploy --target staging` was successful AND `/smo-canary` came back GREEN +- Lana re-ran `/smo-qa-run` on the live staging URL (not just the dev verify) and PASS +- Release PR `dev → main` is merged +- Day is not Friday after 2pm Dubai (MENA weekend starts; rollback window shrinks) + +### 5.4 When to engage `/careful` or `/guard` + +`/smorch-dev-start` Layer 2 suggests these. The suggestions fire when: +- Profile = `prod-server` → `/careful` (warns on destructive ops like `rm -rf`, `DROP TABLE`, `git push --force`) +- `.smorch/project.json:risk_surfaces` contains `auth | payments | migrations` → `/guard` (careful + restricts edits to current directory) +- cwd matches `auth/`, `payments/`, `migrations/`, `secrets/`, `.env*` → `/guard` + +**Accept the suggestion if:** you're touching prod-adjacent code OR sensitive directories. The cost is one extra confirmation prompt per destructive op. The benefit is one prevented incident. + +**Skip the suggestion if:** you're doing read-only investigation OR docs-only work. Wrap with `/unfreeze` if `/guard` is too restrictive for a legitimate cross-directory edit. + +### 5.5 When to call Mamoun vs. just act + +| Action | Just act | Ping Mamoun | +|---|---|---| +| Merge a PR with CI green, no escalation surfaces | ✓ | | +| Tag a release after `/smo-ship` | ✓ | | +| Deploy to staging | ✓ | | +| Deploy to production (smo-prod, eo-prod) | | ✓ | +| Anything touching `auth/`, `payments/`, `migrations/` | | ✓ | +| Force push to main | | ✓ | +| Anything paid (RULE 0) | | ✓ | +| Flip `qa.rollback_drill` to optional | | ✓ | +| Flip `locale` to `en-US` | | ✓ | +| Create a domain, VPS, paid SaaS account | | ✓ | +| SEV1 incident | | ✓ (immediate) | +| SEV2 incident | | ✓ (within 30 min) | +| SEV3 incident | ✓ (log, no urgency) | | +| Rotate a secret (per SOP-16 schedule) | | ✓ (he holds the actual creds) | +| Update a SOP | | ✓ (he reviews SOP changes) | +| Add a new lesson to `~/.claude/lessons.md` | | ✓ (cross-project lessons are CEO-curated) | + +### 5.6 Codex vs Claude Code + +| Task | Tool | Why | +|---|---|---| +| Architecture, planning, review, scoring | Claude Code | SOP-11 default | +| Writing skills, SOPs, CLAUDE.md, handovers | Claude Code | Same | +| /smo-review-pr second-opinion | Claude Code invokes Codex via `gstack:codex` | Codex-as-reviewer is allowed; Codex never writes shipped code | +| /smo-cso --full security cross-check | Codex-as-reviewer | Same | +| Rename 500 instances of foo → bar | ripgrep + sed | Auditable; no Codex needed | +| Convert 200 test files to new framework | `superpowers:subagent-driven-development` | Claude handles this cleanly | +| Translate 1000+ i18n strings | Codex (gated, audit row required) | Mechanical, Codex is cheap + fast | +| Parse 10GB+ of logs into structured data | Codex (gated) | Token cost matters at this scale | + +--- + +## Part 6 — Cadences + +The rhythm of the work. + +### 6.1 Per session + +| When | Action | +|---|---| +| First thing | `/smorch-dev-start` | +| Stuck or unsure | `/smo-dev-guide next` | +| Before context switch | Commit + push current WIP | +| End of session | Verify nothing >1h uncommitted; push everything | + +### 6.2 Per feature/PR + +The chain (Section 2.2). Engineering owns through `/smo-handover`. QA owns `/smo-qa-handover-score` + `/smo-qa-run`. Engineering owns `/smo-ship` + `/smo-deploy`. Auto-composition handles `/smo-verify`, `/smo-simplify`, `/smo-canary`, `/smo-document` without you typing them. + +### 6.3 Daily + +| When | What | Owner | +|---|---|---| +| Morning | `/smo-health` — multi-server health roll-up | Mamoun or on-call | +| Throughout | `/smo-dev-guide next` as needed | You | +| Nightly (cron) | `/smo-cso --daily` (8/10 gate, blocks CI on findings) | Automated | +| Nightly (cron) | `sync-from-github.sh` on all 4 servers + your laptop | Automated | +| Nightly (cron) | drift detectors (3-tier: git, config, plugin) | Automated | + +### 6.4 Weekly / bi-weekly + +| When | What | Owner | +|---|---|---| +| End of sprint (14d) | `/smo-retro` — cross-project patterns, lesson candidates | Mamoun + QA | +| End of sprint | Review `docs/qa-scores/trend.csv` per project — declining = problem | Mamoun | +| End of sprint | Review `docs/handovers/trend.csv` — Lana flags consistent dev gaps | QA | +| End of sprint | Prune stale `.claude/lessons.md` (>90d untriggered) via /smo-retro | Mamoun | + +### 6.5 Monthly + +| When | What | Owner | +|---|---|---| +| First sprint of month | `/smo-cso --full` (deep scan, 2/10 bar) | Mamoun | +| First sprint of month | `/smo-secrets --audit` (90-day rotation SLA per SOP-16) | Mamoun | +| First sprint of month | Review `docs/incidents/` aggregate — 3+ of same class → SOP review | Mamoun | + +### 6.6 Per incident + +| When | What | Owner | +|---|---|---| +| Alert fires | `/smo-triage` (live diagnostic) | First-responder | +| After fix deployed | `/smo-incident SEV{n} {slug}` (post-mortem) | First-responder | +| After SEV1/SEV2 post-mortem | `/smo-cso --post-incident {slug}` (narrow security scan) | First-responder | + +--- + +## Part 7 — Failure Modes (Anti-patterns) + +The patterns that already cost real time. Don't add to the list. + +| Anti-pattern | What it looks like | What it costs | The rule | +|---|---|---|---| +| Edit on server | SSH in, vim, save, restart | Drift detector catches in 1h; auto-rollback fires mid-next-deploy; ½ day cleanup | L-009 | +| Skip `/smorch-dev-start` | "Just opening a quick file" | Subtle env mismatch breaks something hours later | Section 2.2 chain | +| Bypass `/smo-verify` with `--no-block` | "Test is flaky, my code is fine" | Production bug ships, Lana finds it, sent back | QA-DISCIPLINE rule | +| Skip `/smo-score` on "small" PR | "It's a 3-line change" | Eng Q4 type drift compounds across PRs | SOP-02 | +| Round up score from 88 to 92 | "Close enough" | L-001 violation; future-you ships at 78 with same self-justification | L-001 | +| Bundle refactor with feature | "While I'm here…" | Lana has to QA two things; PR diff confusing; either gets sent back | Section 1.2 #3 | +| Force push to main | "Just rewriting one commit message" | Production branch history destroyed; ½ day to restore | L-009 + Section 3.3 | +| Skip rollback drill on customer-data PR | "It's fine, I tested it" | The day the deploy fails, you have no tested recovery path | SOP-01 | +| Self-merge an auth/payments/migrations PR | "It's a small change" | Production security incident with your name on the audit log | Section 3.3 | +| Use Codex without audit row | "I just used it for one thing" | `/smo-score` Engineering Q5 caps at 7; doctrine violation | SOP-11 | +| Commit `.env.local` | "Hook should catch it" | Hooks are best-effort; if it escapes, rotate everything immediately + filter-repo history | L-001 + RULE 0 | +| Develop on local `main` | "Just a quick test" | L-014 trip-wire; `/smorch-dev-start` RED until you switch | Section 3.4 | +| Create a paid resource without RULE 0 approval | "I'll cancel right after testing" | Most providers bill monthly-minimum; cancelling = full month charged | RULE 0 | + +--- + +## Part 8 — When Things Go Sideways + +### 8.1 `/smorch-dev-start` returns RED — what now? + +Read the specific row. Apply the remediation. If unsure, `--fix` handles 90% of common issues. The ones it can't auto-fix: +- Plugin not installed → `claude plugin install smorch-dev@smorch-dev` +- Wrong branch (you're on `main`) → `git checkout dev && git pull --ff-only` +- Stale plugin (cached at 1.5.0 when 1.6.0 is current) → `claude plugin uninstall && reinstall` cycle (see Section 9.1) + +Do NOT proceed with `/smo-*` work on a RED machine. Fix it first. + +### 8.2 Validators fail before commit + +Four validators; run them locally before pushing: +```bash +bash scripts/validate-plugins.sh && \ + bash plugins/smorch-dev/scripts/check-no-l2-reimplementation.sh && \ + bash plugins/smorch-dev/scripts/l3-health-check.sh && \ + bash tests/plugins/v1.6-auto-composition.test.sh +``` + +If any fail, the output names the file + line. Fix the actual issue. Don't bypass with `--no-verify` — the hook caught real risk. + +### 8.3 Plugin version stuck + +If `claude plugin list` shows v1.5.0 but the marketplace has v1.6.0: +```bash +claude plugin marketplace update smorch-dev +claude plugin uninstall smorch-dev@smorch-dev +claude plugin install smorch-dev@smorch-dev +claude plugin list | grep -A1 "smorch-dev$" +``` +The uninstall + reinstall is required; `claude plugin update` has a known naming quirk. + +### 8.4 SSH fails into a server + +- `ssh root@100.X.X.X` hangs → `tailscale up && tailscale status` — mesh down +- SSH succeeds but `git pull` auth-errors → deploy key may have rotated; check `~/.ssh/authorized_keys` on server +- `/smo-deploy` fails at drift pre-check → someone edited on server (L-009 violation); SSH in, investigate before resetting + +### 8.5 Production incident + +1. `/smo-triage` first (live diagnostic, root cause) +2. `/smo-rollback {tag}` if mitigation needs instant revert (will pre-empt the auto-canary rollback if you're faster) +3. Fix on a `hotfix/` branch from main, regression test FIRST +4. Ship + deploy +5. `/smo-incident SEV{n}` within 24h (SEV1) or 48h (SEV2) +6. `/smo-cso --post-incident {slug}` if root cause involved secrets, deps, or infra + +--- + +## Part 9 — Appendices (Quick Reference) + +### 9.1 The 22 commands at a glance + +**smorch-dev (15):** +| Command | One-line purpose | +|---|---| +| `/smorch-dev-start` | Session bootstrap — 4 layers (machine, context, project, input-readiness). RED halts. | +| `/smo-dev-guide [topic]` | In-session reference. `next` = context-aware what-to-run-now. | +| `/smo-plan AC-N.N` | Plan-mode feature plan with plan-eng-review + optional ceo/design review. | +| `/smo-worktree` | Isolated git worktree (required before /smo-code on multi-file work). | +| `/smo-code` | TDD red→green→blue + auto-invokes `/smo-verify` before commit. | +| `/smo-verify` | Live verification — happy + risk_surfaces failures + edge. Hard-gates commit. | +| `/smo-score [--quick \| --full]` | 5-hat composite. Gate 92+, hat floor 8.5. | +| `/smo-bridge-gaps` | Fix lowest hat. Auto-invokes `/smo-simplify` on Eng Q4/Q5. | +| `/smo-simplify` | Code-quality fix loop. AUTO/REVIEW/DEFER. | +| `/smo-benchmark` | Perf regression detection (10% threshold) — gate in /smo-ship if UI/API touched. | +| `/smo-handover [--validate \| --notify]` | Dev → QA brief. /validate calls verification-before-completion. | +| `/smo-qa-handover-score` | QA scores brief. ≥80 to accept, 60-79 send back, <60 reject. | +| `/smo-qa-run` | QA validation: 4 scenarios per AC + locale-gated MENA + rollback drill. | +| `/smo-review-pr` | External adversarial review (fresh subagent). Auto-invoked in /smo-ship. | +| `/smo-ship` | Merge + tag. 6 parallel gates. Auto-invokes `/smo-document` post-merge. | +| `/smo-document` | Post-ship docs sync. README/CLAUDE.md/CHANGELOG. | +| `/smo-triage` | Live bug diagnostic. | +| `/smo-retro` | End-of-sprint retro. Cross-project patterns. | +| `/smo-cso [--daily \| --full \| --post-incident]` | Security audit. | + +**smorch-ops (7):** +| Command | One-line purpose | +|---|---| +| `/smo-deploy --target {staging\|production}` | SSH deploy. Auto-invokes `/smo-canary` post-success. | +| `/smo-canary` | Post-deploy regression watch. Auto-rollback on breach. | +| `/smo-rollback [--auto \| --to {tag}]` | Revert deploy + restart. SLA 90-120s. | +| `/smo-drift` | 3-tier drift report (git, config, plugin). | +| `/smo-health` | Multi-server health roll-up. | +| `/smo-incident SEV{n} {slug}` | Post-mortem writer (SOP-10 template). | +| `/smo-secrets [--audit \| --rotate]` | Rotation tracking per SOP-16. | +| `/smo-skill-sync` | Push skill change → smorch-brain → all machines. | + +### 9.2 Canonical paths + +``` +docs/handovers/ /smo-handover briefs + qa-score reports +docs/qa-scores/ /smo-score reports + trend.csv +docs/qa/ /smo-qa-run reports +docs/incidents/ /smo-incident post-mortems +docs/deploys/ /smo-deploy logs +docs/retros/ /smo-retro sprint reports +docs/verifications/ /smo-verify evidence (v1.6+) +docs/plans/ /smo-plan outputs +docs/security/ /smo-cso reports (v1.6+) +docs/canary/ /smo-canary reports (v1.6+) +docs/simplifications/ /smo-simplify reports (v1.6+) +docs/ships/ /smo-ship trends + /smo-document doc-sync logs +docs/reviews/ /smo-review-pr reports +docs/benchmarks/ /smo-benchmark baselines + reports +.claude/lessons.md per-project lessons (never in docs/) +.smorch/project.json per-project overlay (drives /smo-* behavior) +.smorch/overrides/ per-hat rubric overrides (optional) +.smorch/skills/ per-project skills (optional) +architecture/brd.md BRD with AC-N.N tags +architecture/adrs/ architecture decision records +~/.claude/CLAUDE.md founder's global rules +~/.claude/lessons.md cross-project lessons (auto-loaded SessionStart) +~/.claude/settings.json hooks, env, MCP servers +``` + +### 9.3 Server registry + +| Server | Public IP | Tailscale | Role | +|---|---|---|---| +| eo-prod | 89.117.62.131 | 100.89.148.62 | EO production (eo-mena, eo-scoring) + smorch-brain canonical | +| smo-prod | 62.171.164.178 | 100.108.44.127 | SMO production (SalesMfast, SaaS) + n8n `flow.smorchestra.ai` | +| smo-dev | 62.171.165.57 | 100.83.242.99 | Dev + staging + n8n `testflow.smorchestra.ai` | +| eo-dev | 84.247.172.113 | 100.99.145.22 | EO dev VPS — **canonical dogfood server (SOP-37)** | + +Default to Tailscale IPs. Public IPs are ingress-only, hardened. + +### 9.4 30-second pocket card + +``` +EVERY SESSION: /smorch-dev-start +WHAT NOW? /smo-dev-guide next +NEW FEATURE: /smo-plan AC-N.N → /smo-worktree → /smo-code → /smo-score +SCORE 85-91: /smo-bridge-gaps (auto: /smo-simplify on Eng Q4/Q5) +HANDOVER TO QA: /smo-handover --notify +QA TURN: /smo-qa-handover-score (≥80?) → /smo-qa-run +SHIP: /smo-ship (auto: /smo-review-pr, then /smo-document) +DEPLOY: /smo-deploy (auto: /smo-canary 30-min watch + auto-rollback) +BROKEN: /smo-triage +AFTER FIX: /smo-incident SEV{n} {slug} +END OF SPRINT: /smo-retro +MONTHLY SEC: /smo-cso --full +LOST: /smo-dev-guide stuck +PROD-ADJACENT: accept /careful or /guard suggestion from /smorch-dev-start +DON'T: edit on server | bypass /smo-verify | round up score | spend without RULE 0 +``` + +--- + +## Part 10 — Glossary of Concepts You'll Hear + +| Term | Means | +|---|---| +| L1 / L2 / L3 | Three layers of the OS — commands / SMO skills / gstack+superpowers | +| Auto-composition | v1.6 wiring where parent commands automatically invoke child wrappers (e.g., /smo-code → /smo-verify) | +| Bridge-gaps | The 85-91 score lift cycle — fix the weakest hat to clear the 92 gate | +| Boris discipline | The 2-file framework (CLAUDE.md + BRD) per Boris Cherny; SMO's foundation | +| Canary | Post-deploy production watch (30 min default); auto-rolls back on breach | +| Composite | The 5-hat sum × 2 (range 10-100); ship gate 92 | +| Dogfood | Running our own plugin against itself or a sandbox (SOP-37 parity on eo-dev) | +| Drift | Divergence between local / GitHub / server state — caught hourly by detectors | +| Elegance pause | "Would I write this the same way, knowing what I know now?" — pre-commit reflection | +| Hat | One of 5 scoring dimensions: Product · Architecture · Engineering · QA · UX | +| Hat floor | The minimum any hat can score (8.5 internal, 8.0 student) — composite irrelevant if any hat is below | +| Handover | Dev → QA brief (SOP-13) — the contract that bounds QA scope | +| L-NNN | A lesson — captured failure mode with rule + check (global at ~/.claude, project at .claude/) | +| L3 cascade | The pattern where L1 commands invoke L2 wrappers which delegate craft to L3 | +| MENA | UAE/KSA/QAT/KWT — Middle East / North Africa; the primary ICP region | +| Overlay | Per-project `.smorch/` directory — configuration without forking the plugin | +| Plugin-meta | A repo whose product IS a Claude Code plugin (smorch-dev itself) | +| Risk surface | Pre-declared sensitive area per `.smorch/project.json:risk_surfaces[]` — drives failure-path coverage | +| RULE 0 | The money guardrail — no paid resource without two explicit confirms | +| SEV1-4 | Incident severity (1=outage, 2=major degradation, 3=minor, 4=cosmetic) | +| SOP-NN | Standard Operating Procedure — canonical at smorch-brain/sops/ | +| Sync-from-github | The cron job that pulls smorch-dev + smorch-brain to every machine every 30 min | +| Validator | One of 4 mechanical checks (schema, L2-anti-drift, L3-health, v1.6 test rig) | +| Verb boundary | The distinction between ship/deploy/rollback/triage/incident — words matter | + +--- + +## Changelog + +- **2026-05-27** — Created v1 (covers smorch-dev v1.6.0 + smorch-ops v1.1.0). Authored after the v1.6.0 dogfood validation on eo-dev (composite 92, all hats ≥9). Reframed from a command reference to a strategic OS guide per Mamoun's direction.