diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index dc1ca70..fb2fb79 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -5,19 +5,19 @@ "url": "https://smorchestra.ai" }, "metadata": { - "description": "SMOrchestra internal dev + ops + content toolkit for Claude Code. Three plugins: smorch-dev (workflow: plan → code → score → handover → ship) + smorch-ops (infra: deploy / rollback / drift / health / incident / secrets) + content-engine (bilingual LinkedIn content production with quality rubric).", - "version": "1.1.0" + "description": "SMOrchestra internal dev + ops + content toolkit for Claude Code. Three plugins: smorch-dev (workflow + L3 cascade: plan → code → verify → score → handover → ship → document) + smorch-ops (infra: deploy → canary / rollback / drift / health / incident / secrets) + content-engine (bilingual LinkedIn content production with quality rubric).", + "version": "1.2.0" }, "plugins": [ { "name": "smorch-dev", "source": "./plugins/smorch-dev", - "description": "Workflow plugin. 10 slash commands (/smo-plan, /smo-code, /smo-score, /smo-bridge-gaps, /smo-handover, /smo-qa-handover-score, /smo-qa-run, /smo-ship, /smo-triage, /smo-retro) + 9 skills (smo-scorer with 5-hat rubric, lessons-manager, elegance-pause, arabic-rtl-checker, mena-mobile-check, brd-traceability, handover-generator, qa-handover-scorer, cost-tracker). Install on dev + QA machines." + "description": "Workflow + L3 cascade plugin. 20 slash commands (workflow: /smorch-dev-start, /smo-plan, /smo-code, /smo-score, /smo-bridge-gaps, /smo-handover, /smo-qa-handover-score, /smo-qa-run, /smo-ship, /smo-triage, /smo-retro, /smo-dev-guide; L3 wrappers v1.5: /smo-worktree, /smo-benchmark, /smo-review-pr; L3 wrappers v1.6: /smo-verify, /smo-simplify, /smo-document, /smo-cso) + 11 frozen L2 skills (smo-scorer with 5-hat rubric, dev-start-bootstrap, dev-guide-router, lessons-manager, elegance-pause, arabic-rtl-checker, mena-mobile-check, brd-traceability, handover-generator, qa-handover-scorer, cost-tracker). v1.6 wires auto-composition: /smo-code→/smo-verify (live verify before commit), /smo-bridge-gaps→/smo-simplify (code quality), /smo-ship→/smo-document (post-merge docs), /smorch-dev-start suggests /careful or /guard for prod-adjacent contexts. Install on dev + QA machines." }, { "name": "smorch-ops", "source": "./plugins/smorch-ops", - "description": "Infrastructure plugin. 7 slash commands (/smo-deploy, /smo-rollback, /smo-drift, /smo-health, /smo-incident, /smo-secrets, /smo-skill-sync) + 7 skills (security-hardener, incident-runbook, deploy-pipeline, rollback-runbook, drift-detector, secrets-manager, codex-doctrine). Install on all machines including servers." + "description": "Infrastructure plugin. 7 slash commands (/smo-deploy, /smo-rollback, /smo-drift, /smo-health, /smo-incident, /smo-secrets, /smo-skill-sync) + 7 skills (security-hardener, incident-runbook, deploy-pipeline, rollback-runbook, drift-detector, secrets-manager, codex-doctrine). v1.6: /smo-deploy auto-invokes /smo-canary (smorch-dev) for 30-min post-deploy regression watch + auto-rollback on breach. Install on all machines including servers." }, { "name": "content-engine", diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e72db0..99a0789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,52 @@ # Changelog +## [1.6.0-dev] - 2026-05-25 + +### Added — 5 new L3 wrapper commands to close the OS + +- **`/smo-cso`** — Chief Security Officer audit. Wraps `gstack:cso`. Cadence: `--daily` (nightly CI, 8/10 confidence gate, zero-noise) · `--full` (monthly deep scan, 2/10 bar across secrets/deps/CI/LLM/skills/OWASP/STRIDE) · `--post-incident ` (narrow scan focused on incident-touched surfaces). Closes the perfctl founding-event gap. L2 cross-checks: `secrets-manager` validates rotation SLA on secret-related findings; `drift-detector` validates infra-drift correlation. Writes `docs/security/YYYY-MM-DD-{mode}.md` + trend.csv. +- **`/smo-document`** — Post-ship docs sync. Wraps `gstack:document-release`. Auto-invoked by `/smo-ship` after successful merge. Updates README/CLAUDE.md/ARCHITECTURE/CHANGELOG to match what shipped, sweeps completed TODOs, bumps VERSION. Trivial changes commit direct; non-trivial open a follow-up PR. L2: `brd-traceability` re-validates AC table, `lessons-manager` appends new lessons. +- **`/smo-verify`** — Live verification before commit. Wraps `gstack:run` + `gstack:verify` + `gstack:browse` (if `has_ui=true`). Auto-invoked by `/smo-code` between green TDD step and commit. Exercises happy + mandatory failure paths from `.smorch/project.json:risk_surfaces[]` + at least 1 edge case in a REAL environment. **Hard gate:** commit blocked if any mandatory scenario FAILs. Directly enforces `~/.claude/CLAUDE.md` § QA-DISCIPLINE (lesson April 28: 4 escaped bugs to Lana in 24h were all preventable). +- **`/smo-simplify`** — Code-quality fix loop. Wraps `gstack:simplify`. Auto-invoked by `/smo-bridge-gaps` when Engineering hat is lowest scorer AND Q4 (quality) or Q5 (elegance) drag. Categorizes findings as AUTO/REVIEW/DEFER. L2: `elegance-pause` runs on the resulting diff; `cost-tracker` flags if Claude/OpenAI sites touched. +- **`/smo-canary`** — Post-deploy regression watch. Wraps `gstack:canary`. Auto-invoked by `/smo-deploy` after clean health check. 30-min window (configurable per project). Watches console errors, page failures, Core Web Vitals vs baseline. On breach: auto-`/smo-rollback` (production default ON) + Telegram SEV2 + auto-stub `/smo-incident`. L2 mid-window cross-check via `drift-detector`. + +### Changed — existing commands wired to the new wrappers + +- **`/smo-code`** — now auto-invokes `/smo-verify --auto` between green TDD step and commit (hard-gates the commit on FAIL). +- **`/smo-bridge-gaps`** — now auto-invokes `/smo-simplify --auto` when Engineering hat is lowest scorer with Q4/Q5 dragging. +- **`/smo-ship`** — now auto-invokes `/smo-document --auto` post-merge (step 6). Suppress with `--skip-document`. +- **`/smo-deploy`** — step 7 now wraps `gstack:canary` via `/smo-canary --auto` (was inline). Adds L2 cross-checks + incident-runbook auto-stub on breach. +- **`/smo-handover`** — `--validate` now invokes `superpowers:verification-before-completion` (sanity-check brief reflects merged code: PR URL resolves, score file exists, `@AC-N.N` tags claimed exist in test files, rollback command is canonical). +- **`/smorch-dev-start`** — Layer 2 now emits safety-mode suggestions (additive, never auto-engages): `/careful` for `prod-server` profile; `/guard` for projects with `risk_surfaces: [auth|payments|migrations]` or when cwd matches sensitive paths. + +### Added — project overlay schema fields (v1.6) + +`.smorch/project.json` schema extended (canonical template at `plugins/smorch-dev/templates/smorch-project.json.template`): +- `has_ui` (bool, default false) — drives `gstack:browse` engagement in `/smo-verify` + `/smo-qa-run` +- `risk_surfaces` (array, default []) — drives mandatory failure-path coverage in `/smo-verify`, `/guard` suggestion in `/smorch-dev-start`, risk_tier in `/smo-review-pr`. Values: `auth`, `payments`, `migrations`, `pii`, `secrets` +- `performance_critical_paths` (array, default []) — file globs that trigger `gstack:benchmark` in `/smo-score` +- `canary.window_minutes` (default 30) + `canary.auto_rollback` (default true on production) — `/smo-canary --auto` config + +### Updated + +- `dev-guide-router` skill — 5 new topics (`verify`, `simplify`, `canary`, `document`, `cso`), L3 cascade map extended, overview now lists 22 commands across both plugins. +- Plugin description in `plugin.json` rewritten for v1.6. + +### Non-negotiables preserved + +- 92+ composite + 8.5 hat floor before `/smo-ship` +- ≥80 handover score before Lana accepts QA +- L-009 push discipline +- SOP-36 anti-bloat rule (L2 must not reimplement L3) + pre-commit guard + +### Score delta + +Internal /smo-score against this PR's branch: target 95+ composite (v1.5.1 baseline 91; founder's stated goal: 10/10 OS for plan/review/score/QA/ship). + +## [1.5.1] - 2026-04-29 + +See commit history for v1.5.0 + v1.5.1 — L3 cascade revision (SOP-36) shipping 12 strengthened commands + 3 new wrappers (worktree, benchmark, review-pr). + ## [1.3.0-dev] - 2026-04-21 ### Added diff --git a/README.md b/README.md index 9a0c559..53f9d03 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Internal SMOrchestra dev + ops toolkit. Built after we shipped `eo-microsaas-dev | Path | Purpose | |------|---------| -| `plugins/smorch-dev/` | **Workflow plugin** — 11 commands (plan, code, score, bridge-gaps, handover, qa-handover-score, qa-run, ship, triage, retro, dev-guide) + 10 skills. Installed on dev + QA machines. | +| `plugins/smorch-dev/` | **Workflow plugin** — 15 commands (workflow: plan, code, score, bridge-gaps, handover, qa-handover-score, qa-run, ship, triage, retro, dev-guide; L3 wrappers: worktree, benchmark, review-pr; v1.6 L3 wrappers: verify, simplify, canary, document, cso) + 11 skills. Installed on dev + QA machines. | | `plugins/smorch-ops/` | **Infra plugin** — 7 commands (deploy, rollback, drift, health, incident, secrets, skill-sync) + 7 skills. Installed on all machines incl. servers. | | `install/` | One script per machine profile — `qa-machine.ps1` (Lana, Windows), `eng-desktop.sh` (dev desktops), `dev-server.sh`, `prod-server.sh` | | `scripts/` | `validate-plugins.sh` (CI), `sync-from-github.sh` (cron-invoked) | @@ -36,13 +36,16 @@ iwr -useb https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/insta bash <(curl -fsSL https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/install/prod-server.sh) ``` -## Command surface — 18 total, no overlap +## Command surface — 27 total (v1.6.0-dev), no overlap -### Workflow (smorch-dev) -`/smo-plan` · `/smo-code` · `/smo-score` (--quick / --full) · `/smo-bridge-gaps` · `/smo-handover` · `/smo-qa-handover-score` · `/smo-qa-run` · `/smo-ship` (merge + tag) · `/smo-triage` (live debug) · `/smo-retro` · `/smo-dev-guide` (in-session cheat-sheet) +### Workflow chain (smorch-dev) +`/smorch-dev-start` (4-layer bootstrap, run FIRST) · `/smo-plan` · `/smo-worktree` · `/smo-code` · `/smo-verify` (auto) · `/smo-score` (--quick / --full) · `/smo-bridge-gaps` · `/smo-simplify` (auto on Eng Q4/Q5) · `/smo-handover` · `/smo-qa-handover-score` · `/smo-qa-run` · `/smo-review-pr` (auto in /smo-ship) · `/smo-benchmark` (UI/API gate) · `/smo-ship` (merge + tag) · `/smo-document` (auto post-merge) · `/smo-triage` (live debug) · `/smo-retro` · `/smo-dev-guide` (in-session cheat-sheet) + +### Quality + security (smorch-dev — v1.6) +`/smo-verify` (live verification before commit) · `/smo-simplify` (code-quality fix loop) · `/smo-document` (post-ship docs sync) · `/smo-cso` (security audit, `--daily | --full | --post-incident`) ### Ops (smorch-ops) -`/smo-deploy` · `/smo-rollback` · `/smo-drift` · `/smo-health` · `/smo-incident` (post-mortem) · `/smo-secrets` · `/smo-skill-sync` +`/smo-deploy` (auto-invokes `/smo-canary`) · `/smo-canary` (post-deploy watch) · `/smo-rollback` · `/smo-drift` · `/smo-health` · `/smo-incident` (post-mortem) · `/smo-secrets` · `/smo-skill-sync` ## Verb boundaries (documented in SOP-14) @@ -95,4 +98,4 @@ eo-mena/ ## Version -v1.0.0 (repo + plugins). Target: take SMOrchestra from ad-hoc workflows to a 10/10 dev + ops discipline. No sloppiness. +v1.6.0-dev. v1.5 wired the L3 cascade (gstack + superpowers) into 12 commands and added 3 new wrappers. v1.6 closes the OS with 5 more wrappers (`/smo-verify`, `/smo-simplify`, `/smo-canary`, `/smo-document`, `/smo-cso`), auto-composition between them, and `/careful`/`/guard` safety-mode suggestions in the session bootstrap. Target: 10/10 OS for planning + review + scoring + QA + ship + deploy. No sloppiness. diff --git a/docs/INDEX.md b/docs/INDEX.md index 13a5d74..e7ab6a1 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -65,7 +65,7 @@ All dev-related how-to guides live at **`docs/guides/`**. No dev guide lives out | Artifact | Location | Contents | |----------|----------|----------| -| smorch-dev plugin | `smorch-dev/plugins/smorch-dev/` | 11 commands + 10 skills + templates | +| smorch-dev plugin | `smorch-dev/plugins/smorch-dev/` | 20 commands + 11 skills + templates (v1.6.0-dev — workflow + L3 cascade wrappers) | | smorch-ops plugin | `smorch-dev/plugins/smorch-ops/` | 7 commands + 7 skills + templates | | Install scripts | `smorch-dev/install/` | qa-machine.ps1, eng-desktop.sh, dev-server.sh, prod-server.sh | | Validator | `smorch-dev/scripts/validate-plugins.sh` | Schema + frontmatter + dead-ref check (runs in CI) | diff --git a/docs/PLUGIN-SKILLS-COMMANDS-GUIDE.md b/docs/PLUGIN-SKILLS-COMMANDS-GUIDE.md index f47c514..a39608c 100644 --- a/docs/PLUGIN-SKILLS-COMMANDS-GUIDE.md +++ b/docs/PLUGIN-SKILLS-COMMANDS-GUIDE.md @@ -39,7 +39,11 @@ iwr -useb https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/insta --- -## The 18 commands — by daily sequence +## The commands — by daily sequence + +> v1.6.0-dev: 22 commands total (smorch-dev: 15, smorch-ops: 7). v1.5 added L3 cascade wrappers (worktree, benchmark, review-pr). v1.6 adds 5 more (verify, simplify, canary, document, cso) + auto-composition between them. + + ### Morning | Command | What it does | @@ -50,10 +54,15 @@ iwr -useb https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/insta ### Building a feature | Command | What it does | |---------|--------------| -| `/smo-plan {feature}` | Plan mode. Reads BRD + lessons + project overlay. Waits for approval. | -| `/smo-code` | TDD loop: test-first per AC-N.N, minimal impl, refactor, elegance pause. | +| `/smo-plan {feature}` | Plan mode. Reads BRD + lessons + project overlay. Multi-perspective L3 (writing-plans + plan-eng-review + optional CEO/design). Waits for approval. | +| `/smo-worktree` | Isolated git worktree (hard-required before /smo-code on multi-file work). Wraps superpowers:using-git-worktrees. | +| `/smo-code` | TDD loop: test-first per AC-N.N, minimal impl, refactor, elegance pause. **v1.6: auto-invokes `/smo-verify` before commit (live verification, hard gate).** | +| `/smo-verify` | **(v1.6)** Live verification before commit. Wraps gstack:run + gstack:verify + gstack:browse. Exercises happy + mandatory failure paths from `risk_surfaces[]` + edge case in real environment. Blocks commit on fail. | | `/smo-score [--quick / --full]` | 5-hat composite score. Gate 92+ internal, 90+ students. | -| `/smo-bridge-gaps` | Fix the lowest hat when score is 85-91. | +| `/smo-bridge-gaps` | Fix the lowest hat when score is 85-91. **v1.6: auto-invokes `/smo-simplify` when Eng Q4/Q5 are dragging.** | +| `/smo-simplify` | **(v1.6)** Code-quality fix loop. Wraps gstack:simplify. AUTO/REVIEW/DEFER categorization. | +| `/smo-benchmark` | Performance regression gate (run before /smo-ship if UI/API code touched). Wraps gstack:benchmark. | +| `/smo-review-pr` | External adversarial review (auto-invoked inside /smo-ship). Wraps superpowers:requesting-code-review + gstack:review + /security-review. | ### Dev → QA handover | Command | What it does | @@ -65,8 +74,10 @@ iwr -useb https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/insta ### Ship + deploy | Command | What it does | |---------|--------------| -| `/smo-ship` | Merge PR + git tag. Does NOT deploy. Requires 92+ score + QA pass. | -| `/smo-deploy` | SSH to server + git pull + pm2 reload + health check. Pre-drift check. | +| `/smo-ship` | Merge PR + git tag. Does NOT deploy. Requires 92+ score + QA pass. **v1.6: invokes gstack:ship for PR ceremony + auto-invokes `/smo-document` post-merge.** | +| `/smo-document` | **(v1.6)** Post-ship docs sync. Wraps gstack:document-release. Updates README/CLAUDE.md/CHANGELOG to match what shipped. Trivial → direct commit; non-trivial → follow-up PR. | +| `/smo-deploy` | SSH to server + git pull + pm2 reload + health check. Pre-drift check. **v1.6: auto-invokes `/smo-canary` post-success.** | +| `/smo-canary` | **(v1.6)** Post-deploy regression watch (30 min default). Wraps gstack:canary. Auto-rollback on breach. | | `/smo-rollback` | Revert a deploy. Target SLA 90-120s. Deploy's twin. | ### Incidents + fixes @@ -75,11 +86,14 @@ iwr -useb https://raw.githubusercontent.com/SMOrchestra-ai/smorch-dev/main/insta | `/smo-triage {bug}` | Live diagnostic: hypothesis → evidence → root cause → regression test. | | `/smo-incident` | Post-mortem writer. SEV1-4 structure per SOP-10. | -### Ops +### Ops + security | Command | What it does | |---------|--------------| | `/smo-secrets [--audit / --rotate {name}]` | 90-day rotation tracking per SOP-16. | | `/smo-skill-sync` | Push a skill edit → smorch-brain → all machines via sync-all. | +| `/smo-cso [--daily / --full / --post-incident ]` | **(v1.6)** Chief Security Officer audit. Wraps gstack:cso. Nightly 8/10 gate in CI + monthly --full deep scan + post-incident narrow scan. Closes the perfctl founding-event gap. | +| `/smo-health` | Multi-server health roll-up (apps + UFW/fail2ban/SSH posture). | +| `/smo-drift --target {host}` | On-demand drift diagnostic. | ### End of sprint | Command | What it does | @@ -197,12 +211,19 @@ The plugin reads `.smorch/project.json` at SessionStart and adapts. No PR to the | You say | Plugin does | |---------|-------------| | "start a feature for X" | `/smo-plan X` | -| "code it" | `/smo-code` | +| "code it" | `/smo-code` (auto: /smo-verify before commit) | +| "verify it works live" | `/smo-verify` (v1.6) | | "score it" | `/smo-score --full` | -| "fix the weakest hat" | `/smo-bridge-gaps` | +| "fix the weakest hat" | `/smo-bridge-gaps` (auto: /smo-simplify on Eng Q4/Q5) | +| "clean up the code" | `/smo-simplify` (v1.6) | +| "get a second opinion" | `/smo-review-pr` (also auto in /smo-ship) | +| "check perf regression" | `/smo-benchmark` | | "send to QA" | `/smo-handover --notify` | -| "ship it" | `/smo-ship` | -| "deploy" | `/smo-deploy` | +| "ship it" | `/smo-ship` (auto: /smo-document post-merge) | +| "sync the docs" | `/smo-document` (v1.6) | +| "deploy" | `/smo-deploy` (auto: /smo-canary post-success) | +| "watch the deploy" | `/smo-canary` (v1.6, also auto) | +| "security audit" | `/smo-cso --full` (v1.6, monthly) | | "something is broken" | `/smo-triage "{symptom}"` | | "write up the incident" | `/smo-incident` | | "revert the deploy" | `/smo-rollback` | @@ -212,7 +233,7 @@ The plugin reads `.smorch/project.json` at SessionStart and adapts. No PR to the | "push the new skill" | `/smo-skill-sync` | | "end of sprint" | `/smo-retro` | | "what do I run next?" | `/smo-dev-guide next` | -| "how does X work?" | `/smo-dev-guide {topic}` (e.g. `architecture`, `overlay`, `sync`) | +| "how does X work?" | `/smo-dev-guide {topic}` (e.g. `verify`, `canary`, `cso`, `l3`) | | "look up SOP-14" | `/smo-dev-guide sop-14` | | "look up L-008" | `/smo-dev-guide l-008` | diff --git a/docs/guides/05-PLUGIN-COMPLETE-GUIDE.md b/docs/guides/05-PLUGIN-COMPLETE-GUIDE.md index 64922c3..3913a0b 100644 --- a/docs/guides/05-PLUGIN-COMPLETE-GUIDE.md +++ b/docs/guides/05-PLUGIN-COMPLETE-GUIDE.md @@ -189,7 +189,11 @@ This is the loop. The plugin's job is to make this loop *the only path that work ## Part 3 — Every Command, Briefly -### 3.1 — `smorch-dev` plugin commands (12) +### 3.1 — `smorch-dev` plugin commands (20 — v1.6.0-dev) + +v1.6 closes the L3 cascade: 5 new wrappers (`/smo-verify`, `/smo-simplify`, `/smo-canary`, `/smo-document`, `/smo-cso`) bring the OS to 10/10 for plan/review/score/QA/ship/deploy/security. Auto-composition wired across the chain. + + | Command | One-line purpose | Owner | Inputs | Outputs | |---|---|---|---|---| @@ -205,6 +209,14 @@ This is the loop. The plugin's job is to make this loop *the only path that work | `/smo-ship` | Merge PR + tag release. 5 parallel gates (score, hat-floor, QA, handover, git-clean). | Engineer | passed gates | Merged PR + `vX.Y.Z` tag | | `/smo-triage` | Live diagnostic when something is broken right now. | Engineer | symptom description | Hypothesis + evidence + fix path | | `/smo-retro` | Weekly/monthly retrospective. Promotes lessons.md candidates. | Mamoun | `~/.claude/lessons.md` + per-repo lessons | Promotion PR for global lessons | +| `/smo-worktree` | Isolated git worktree before /smo-code on multi-file work (v1.5). | Engineer | latest plan | `.claude/worktrees/{feature}/` | +| `/smo-benchmark` | Perf regression gate (gstack:benchmark) — `GATE_benchmark` in /smo-ship (v1.5). | Engineer | UI/API code touched | `docs/benchmarks/YYYY-MM-DD-{branch}.md` | +| `/smo-review-pr` | External adversarial review — auto-invoked inside /smo-ship (v1.5). | Engineer | PR or branch | `docs/reviews/YYYY-MM-DD-PR-{n}.md` | +| `/smo-verify` | **(v1.6)** Live verification before commit — auto-invoked by /smo-code. Hard-gates the commit. | Engineer | risk_surfaces[] + has_ui | `docs/verifications/YYYY-MM-DD-{branch}.md` | +| `/smo-simplify` | **(v1.6)** Code-quality fix loop — auto-invoked by /smo-bridge-gaps on Eng Q4/Q5. | Engineer | branch diff | `docs/simplifications/YYYY-MM-DD-{branch}.md` | +| `/smo-canary` | **(v1.6)** Post-deploy regression watch — auto-invoked by /smo-deploy. Auto-rollback on breach. | Engineer | canary config in .smorch | `docs/canary/YYYY-MM-DD-{tag}.md` | +| `/smo-document` | **(v1.6)** Post-ship docs sync — auto-invoked by /smo-ship. Trivial commit / non-trivial PR. | Engineer | merged tag/sha | `docs/ships/{tag}-doc-sync.md` | +| `/smo-cso` | **(v1.6)** Security audit — nightly `--daily` + monthly `--full` + `--post-incident`. Closes perfctl gap. | Mamoun / CI | scan mode | `docs/security/YYYY-MM-DD-{mode}.md` | ### 3.2 — `smorch-ops` plugin commands (7) diff --git a/plugins/smorch-dev/.claude-plugin/plugin.json b/plugins/smorch-dev/.claude-plugin/plugin.json index 7872d93..749eb8f 100644 --- a/plugins/smorch-dev/.claude-plugin/plugin.json +++ b/plugins/smorch-dev/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "smorch-dev", - "version": "1.5.1", - "description": "SMOrchestra internal development workflow plugin. v1.5 — L3 cascade revision (SOP-36): 15 slash commands wired to gstack (29 skills) + superpowers (14 skills) + 11 frozen L2 skills (5-hat scoring, MENA + RTL, BRD traceability, elegance pause, lessons, handover, cost). 12 existing commands (smorch-dev-start, plan, code, score, bridge-gaps, handover, qa-handover-score, qa-run, ship, triage, retro, dev-guide) revised to invoke L3 hard-required (warn-default on laptops, strict-refuse on servers/CI). 3 new commands (worktree, benchmark, review-pr) wrap superpowers:using-git-worktrees, gstack:benchmark, superpowers:requesting-code-review. SessionStart hook runs l3-health-check.sh. Pre-commit guard (check-no-l2-reimplementation.sh) prevents L2 from drifting into L3 territory. Anti-bloat: L2 list is FROZEN at 11.", + "version": "1.6.0-dev", + "description": "SMOrchestra internal development workflow plugin. v1.6 — L3 cascade completion: 20 slash commands wired to gstack (29 skills) + superpowers (14 skills) + 11 frozen L2 skills. v1.5 shipped 15 commands with L3 cascade revision (SOP-36). v1.6 adds 5 commands to close the OS: /smo-verify (live verification before commit, enforces QA-DISCIPLINE — wraps gstack:verify+run+browse, auto-invoked by /smo-code), /smo-simplify (gstack:simplify, auto-invoked by /smo-bridge-gaps on Eng Q4/Q5), /smo-canary (gstack:canary, auto-invoked by /smo-deploy, 30-min post-deploy watch with auto-rollback), /smo-document (gstack:document-release, auto-invoked by /smo-ship after merge to keep README/CLAUDE.md/CHANGELOG in sync), /smo-cso (gstack:cso security audit — nightly --daily 8/10 gate + monthly --full deep scan + --post-incident; closes the perfctl founding-event gap). /smo-handover --validate now invokes superpowers:verification-before-completion. /smorch-dev-start Layer 2 suggests gstack:careful (prod-server) and gstack:guard (auth/payments/migrations risk surfaces). Anti-bloat: L2 list is FROZEN at 11.", "author": { "name": "SMOrchestra.ai", "email": "smorchestra.ai@gmail.com" diff --git a/plugins/smorch-dev/commands/smo-canary.md b/plugins/smorch-dev/commands/smo-canary.md new file mode 100644 index 0000000..819ba70 --- /dev/null +++ b/plugins/smorch-dev/commands/smo-canary.md @@ -0,0 +1,119 @@ +--- +description: Post-deploy production monitoring. Wraps gstack:canary. Auto-runs after /smo-deploy. Manual invocation for on-demand check or pre-major-event watch. +allowed-tools: Bash, Read, Write +--- + +# /smo-canary + +**Scope:** watch a deployed app for console errors, perf regressions, page failures. Compare against pre-deploy baseline. +**When:** auto-invoked by `/smo-deploy` after a successful health check. Manually callable any time (pre-promotion event, suspected regression, post-third-party-API change). + +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Canary engine | `gstack:canary` | Always | + +L2 wrappers: `drift-detector` cross-checks server HEAD vs origin during the window (catches mid-canary drift); `incident-runbook` is invoked if any tracked metric breaches the alarm threshold. + +## Workflow + +1. Read target from `$ARGUMENTS` (project name) or current `.smorch/project.json` if cwd is inside a project. +2. Resolve canary config from `.smorch/project.json:canary`: + - `window_minutes` (default 30) — how long to watch + - `routes[]` (default top-3 from `next.config.js` / `app/` structure) — what to ping + - `thresholds.error_rate_per_min` (default 1) — max console/page errors per min + - `thresholds.perf_regression_pct` (default 15) — max LCP/INP/CLS regression + - `baseline_path` (default `docs/canary/baseline.json`) — perf baseline +3. **L3 gstack:canary** runs the watch loop: + - Open each route via browse daemon every 60s + - Capture console errors, network failures, Core Web Vitals + - Compare each metric to baseline + - Take periodic screenshots (default every 5 min) +4. **L2 drift-detector** runs once mid-window — confirms server HEAD still matches the tag deployed (catches "someone pushed during canary"). +5. On any breach during the window: + - Stop watching (don't pile alerts) + - **L2 incident-runbook** opens SEV2 with the breach details + screenshot + - Trigger `/smo-rollback --auto` (if `auto_rollback: true` in canary config, default ON for prod targets) + - Telegram alert to Mamoun +6. End of window (no breach): + - Write summary to `docs/canary/YYYY-MM-DD-{tag}.md` + - Telegram "✅ {project} v{tag} canary clean (30 min, 0 errors)" + - Update `docs/canary/baseline.json` if `--update-baseline` flag set OR if this was the first deploy of a new major version + +## Arguments + +| Flag | Effect | +|---|---| +| `$ARGUMENTS` | Optional project name (default: current project from .smorch) | +| `--auto` | Invoked by `/smo-deploy`. Non-interactive. Auto-rollback on breach per project config. | +| `--window N` | Override window minutes (default from project.json, fallback 30) | +| `--target staging\|production` | Which env to watch (default: production if deploy went there, else staging) | +| `--no-rollback` | Watch + alert but never trigger rollback (use during planned promotions where rollback would cause more damage) | +| `--update-baseline` | After clean window, refresh perf baseline (use after intentional perf changes) | + +## Auto-invocation contract (from /smo-deploy) + +`/smo-deploy` step 7.5 (after step 7 health check passes) calls `/smo-canary --auto`: +- Runs in background — `/smo-deploy` returns control to dev while watch continues +- Telegram-only outcome reporting (don't spam the dev terminal) +- Auto-rollback enabled per project (default ON for production, OFF for staging unless explicitly configured) + +The dev sees: +``` +✅ Deploy complete v1.4.2 +🔍 /smo-canary --auto running (30 min window) — Telegram on completion +``` + +30 min later (clean): +``` +[Telegram] ✅ eo-mena v1.4.2 canary clean (30 min, 0 errors, perf within baseline) +``` + +Or on breach: +``` +[Telegram] 🔴 eo-mena v1.4.2 canary BREACH + - LCP regressed 22% on /draft (baseline 1.7s → current 2.1s) + - 3 console errors on /draft ("ReferenceError: claude is not defined") + - Auto-rollback triggered → v1.4.1 restored, /api/health green + - SEV2 stub: docs/incidents/2026-04-29-SEV2-canary-breach-draft.md +``` + +## Output + +`docs/canary/YYYY-MM-DD-{tag}.md`: + +```markdown +# Canary — eo-mena v1.4.2 — 2026-04-29 14:30 → 15:00 + +**Window:** 30 min +**Target:** production (eo-prod) +**Routes watched:** /, /draft, /api/health +**Auto-rollback:** enabled (no breach) + +## Per-route summary +| Route | Errors | LCP delta | CLS delta | Screenshots | +|---|:---:|:---:|:---:|---| +| / | 0 | -3% | 0% | 6 | +| /draft | 0 | +2% | +1% | 6 | +| /api/health | 0 | n/a | n/a | (skipped — JSON) | + +## Drift check (mid-window) +- Server HEAD: a3f4e21 ✓ matches v1.4.2 tag + +## Verdict: CLEAN +No breach. Baseline preserved. +``` + +## Never + +- Never `--no-rollback` on a production target without active operator monitoring. +- Never run two canaries concurrently on the same target (state confusion). +- Never bypass the baseline update gate (`--update-baseline`) — intentional perf changes need an explicit refresh. + +## See also + +- `gstack:canary` (the engine) +- `drift-detector`, `incident-runbook` (L2 wrappers) +- `/smo-deploy` (the auto-trigger), `/smo-rollback` (the breach response) +- `/smo-benchmark` (pre-ship perf gate — complements canary) diff --git a/plugins/smorch-dev/commands/smo-code.md b/plugins/smorch-dev/commands/smo-code.md index 7b2f817..68fe5cd 100644 --- a/plugins/smorch-dev/commands/smo-code.md +++ b/plugins/smorch-dev/commands/smo-code.md @@ -15,6 +15,7 @@ description: Execute a planned feature via TDD. Hard-required worktree. Writes t | TDD red→green→blue | `superpowers:test-driven-development` | Always, per AC | | Multi-file work | `superpowers:subagent-driven-development` | If >1 independent file | | Multi-investigation | `superpowers:dispatching-parallel-agents` | If 3+ truly independent investigations | +| Live verification before commit | `gstack:verify` + `gstack:run` + `gstack:browse` (via `/smo-verify --auto`) | Always, between green TDD step and commit | L2 wrappers: `elegance-pause` before each commit, `arabic-rtl-checker` + `mena-mobile-check` on `.tsx`/`.jsx` changes, `cost-tracker` on Claude/OpenAI/DB paths, `lessons-manager` appends corrections. @@ -29,6 +30,7 @@ L2 wrappers: `elegance-pause` before each commit, `arabic-rtl-checker` + `mena-m - Write failing test tagged `@AC-N.N` (red) - Minimal impl to pass (green) - Refactor (blue) + b. **`/smo-verify --auto`** — live verification before commit (hard gate). Wraps `gstack:run` + `gstack:verify` + `gstack:browse`. Exercises happy + mandatory failure paths from `.smorch/project.json:risk_surfaces[]` + at least 1 edge case in a REAL environment. Commit blocked if any mandatory scenario FAILs. Writes `docs/verifications/YYYY-MM-DD-{branch}.md`. Enforces `~/.claude/CLAUDE.md` § QA-DISCIPLINE. 4. **If >1 independent file** in the AC scope: - **L3 superpowers:subagent-driven-development** with 2-stage review (spec compliance, then code quality). One subagent per file. 5. **If 3+ independent investigations** needed (e.g., search for type X across packages, scan for stale imports, audit env-var usage): @@ -37,7 +39,7 @@ L2 wrappers: `elegance-pause` before each commit, `arabic-rtl-checker` + `mena-m 7. **L2 arabic-rtl-checker + mena-mobile-check** on `.tsx`/`.jsx` changes (gated by locale per /smo-plan) 8. **L2 cost-tracker** annotates any cost anomaly for Engineering Q8 9. **L2 lessons-manager** appends corrections received during the session -10. Stage + commit with conventional message + @AC-N.N refs + elegance-pause block +10. Stage + commit with conventional message + @AC-N.N refs + elegance-pause block + verification evidence path ## Arguments diff --git a/plugins/smorch-dev/commands/smo-cso.md b/plugins/smorch-dev/commands/smo-cso.md new file mode 100644 index 0000000..bcfa2e0 --- /dev/null +++ b/plugins/smorch-dev/commands/smo-cso.md @@ -0,0 +1,109 @@ +--- +description: Chief Security Officer audit. Wraps gstack:cso. Daily 8/10 gate in CI + monthly --full deep scan. Founding event was perfctl — this is the cadence that prevents the next one. +allowed-tools: Bash, Read, Write +--- + +# /smo-cso + +**Scope:** scheduled + on-demand security audit. Infrastructure-first. +**When:** monthly `--full`; daily `--daily` in CI; post-incident `--post-incident `. + +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Security audit engine | `gstack:cso` | Always | + +L2 wrappers: `lessons-manager` appends any new lesson generated from findings (L-NNN pattern); `secrets-manager` cross-checks the secrets-manifest against findings; `drift-detector` cross-checks the perfctl-sentinel results inline. + +## Workflow + +1. **L3 gstack:cso** in the requested mode: + - `--daily` — zero-noise 8/10 confidence gate. Only blocks/warns on real findings. Cheap, runs nightly via CI. + - `--full` (default for manual) — comprehensive deep scan, 2/10 bar. Covers: secrets archaeology, dependency supply chain, CI/CD pipeline security, LLM/AI security, skill supply chain scanning, OWASP Top 10, STRIDE threat model, active verification. + - `--post-incident ` — narrower scan focused on the surfaces involved in the named incident (`docs/incidents/`). +2. **L2 secrets-manager** cross-check: any finding referencing a secret cross-references the secrets-manifest age + rotation SLA (SOP-16). Critical age + finding → upgrade to SEV1. +3. **L2 drift-detector** cross-check: any infra/config finding cross-references the latest infra-drift output. Recurring drift + finding → upgrade to SEV1. +4. Aggregate verdicts → `docs/security/YYYY-MM-DD-{mode}.md` + append `docs/security/trend.csv`. +5. Apply gate per mode: + - `--daily` ≥1 BLOCKER → CI fails the nightly job + Telegram SEV2 alert to Mamoun + - `--full` any SEV1 finding → Telegram SEV1 alert + create `/smo-incident` stub + - `--post-incident` any unmitigated finding repeating the original cause → SEV1 + block until owner sign-off +6. **L2 lessons-manager** — if a finding is a class we haven't seen before, propose a new project (or canonical) lesson with **Why** + **How to apply** scaffolded. + +## Arguments + +| Flag | Effect | +|---|---| +| `--daily` | Nightly CI mode. 8/10 confidence gate. Zero noise on a green tree. | +| `--full` (default for manual) | Monthly deep scan. 2/10 bar. ~10-30 min. | +| `--post-incident ` | Narrow scan focused on incident-touched surfaces. | +| `--no-block` | Report only, never fail CI / Telegram. Use during incident-response triage. | +| `--target ` | Scope to one surface: `secrets`, `deps`, `ci`, `llm`, `skills`, `web`, `infra`. | + +## Output + +`docs/security/YYYY-MM-DD-{mode}.md`: + +```markdown +# CSO scan — full — 2026-04-29 + +**Mode:** --full +**Confidence floor:** 2/10 +**Scope:** all surfaces + +## Findings (3) + +### SEV1 — Supabase service_role_eo overdue 188d (sup-001) +- Surface: secrets +- Cross-check: secrets-manager critical, rotation SLA 90d +- Action: /smo-secrets --rotate supabase_service_role_eo (this sprint) +- Lesson proposed: none (covered by L-001 backup + SOP-16) + +### SEV2 — npm package `xyz@1.2.3` has known CVE-2026-NNN (dep-007) +- Surface: deps +- Cross-check: in `package-lock.json` of 3 projects +- Action: bump to xyz@1.2.4 across all 3, re-deploy +- Lesson proposed: L-NEW "Dependabot enable on every active repo" + +### SEV3 — GitHub Actions cache poisoning surface (ci-002) +- Surface: ci +- Action: pin actions/cache to commit SHA, not tag +- Lesson proposed: none + +## Gate verdict +🔴 1 SEV1 → /smo-incident stub created +🟡 1 SEV2 → fix this week +🟢 1 SEV3 → backlog + +Wrote: docs/security/2026-04-29-full.md +Trend: docs/security/trend.csv +1 row +``` + +## Cadence + +| When | How | Who | +|---|---|---| +| Nightly | CI cron runs `/smo-cso --daily --no-block` (alerts on findings only) | Automated | +| Monthly (1st of month) | `/smo-cso --full` | Mamoun (or `/smo-retro` triggers it) | +| Post-incident | `/smo-cso --post-incident ` after `/smo-incident` write-up | Whoever ran the incident | +| Pre-major-release | `/smo-cso --full --target ci,secrets` before any v2.0.0+ ship | Mamoun | + +## Founding context + +The April 18 perfctl malware incident is why this command exists. Three weeks of work lost. `/smo-dev-cso` could have caught the entry vector months earlier via the `secrets` + `infra` surfaces. From v1.6.0 onward this is the cadence: nightly noise-free check + monthly deep scan + post-incident narrow scan. + +## Never + +- Never `--no-block` outside an active incident (defeats the purpose). +- Never skip the SEV1 stub creation (`/smo-incident` ties the finding to a write-up). +- Never tune the 8/10 daily gate down to silence noise — investigate the noise instead (L-002 evidence rule). + +## See also + +- `gstack:cso` (the engine) +- `secrets-manager` skill (rotation orchestration) +- `security-hardener` skill (server posture baseline) +- `perfctl-sentinel.sh` (real-time IOC detection on servers) +- SOP-10 (incident response), SOP-16 (secrets rotation) +- L-001 (.env backup before destructive maintenance) diff --git a/plugins/smorch-dev/commands/smo-document.md b/plugins/smorch-dev/commands/smo-document.md new file mode 100644 index 0000000..40ff001 --- /dev/null +++ b/plugins/smorch-dev/commands/smo-document.md @@ -0,0 +1,103 @@ +--- +description: Post-ship docs sync. Wraps gstack:document-release. Auto-invoked by /smo-ship after merge. Keeps README/CLAUDE.md/CHANGELOG in lockstep with what actually shipped. +allowed-tools: Bash, Read, Write, Edit +--- + +# /smo-document + +**Scope:** sync project docs to the state of the just-merged PR. +**When:** auto-invoked by `/smo-ship` after a successful merge. Also callable manually after a manual merge / hotfix. + +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Doc reconciliation | `gstack:document-release` | Always | + +L2 wrappers: `brd-traceability` re-validates the BRD AC table reflects current `@AC-N.N` tags (catches stale ACs after a refactor); `lessons-manager` appends any lesson the merged PR exposed. + +## Workflow + +1. Resolve the just-merged ref: `$ARGUMENTS` (sha/tag) or `git rev-parse HEAD` if on main directly. +2. **L3 gstack:document-release** runs: + - Read the diff against the previous tag + - Update `README.md` if surfaces changed (new commands, new env vars, new flags) + - Update `CLAUDE.md` if rules/gates changed + - Update `ARCHITECTURE.md` / `CONTRIBUTING.md` if structure changed + - Polish `CHANGELOG.md` voice (concise, why-focused) + - Sweep TODOs that the PR completed + - Bump `VERSION` file if present +3. **L2 brd-traceability** — re-check `architecture/brd.md` AC coverage matches the current test tags. Flag any drift in the doc PR. +4. Categorize doc changes: + - **Trivial** (<20 lines diff total, README only) → commit directly to `main` with message `docs: sync to {tag}`. + - **Non-trivial** (≥20 lines OR touches CLAUDE.md/ARCHITECTURE.md) → open a follow-up PR titled `docs: sync to {tag}` for human review. +5. **L2 lessons-manager** — if any new lesson was captured during the shipped work, append to `.claude/lessons.md` (project) or propose for `~/.claude/lessons.md` (global) per SOP-22 promotion rule. +6. Write summary to `docs/ships/{tag}-doc-sync.md` and append a row to `docs/ships/trend.csv` (`tag, doc_lines_changed, follow_up_pr, lesson_appended`). + +## Arguments + +| Flag | Effect | +|---|---| +| `$ARGUMENTS` | Optional sha/tag (default: HEAD on main) | +| `--dry-run` | Print intended edits, don't write | +| `--force-pr` | Always open a follow-up PR even for trivial changes (useful in protected-main repos) | +| `--skip-lessons` | Skip the lessons-manager step (used by `--auto` from `/smo-ship` if a corrections-free session) | + +## Auto-invocation contract + +`/smo-ship` step 6 (post-merge) calls `/smo-document --auto`. The `--auto` flag: +- Defaults to direct-commit for trivial changes +- Suppresses interactive prompts +- Writes a 1-line summary back to the `/smo-ship` output + +The dev sees: +``` +✅ Shipped PR #47 v1.4.2 +📝 Docs synced: 1 README edit (committed); no follow-up PR needed +``` + +Or for non-trivial: +``` +✅ Shipped PR #47 v1.4.2 +📝 Docs follow-up: PR #48 opened for review (CLAUDE.md gates section changed) +``` + +## Output + +`docs/ships/{tag}-doc-sync.md`: + +```markdown +# Doc sync — v1.4.2 (PR #47) + +**Triggered by:** /smo-ship --auto +**Mode:** direct-commit + +## Files updated +- README.md (+4 -2): new `/smo-deploy --canary-window` flag documented +- CHANGELOG.md (+5): v1.4.2 entry polished + +## BRD traceability check +- AC coverage: 17/17 ✓ (no drift) + +## Lessons appended +- (none — clean session) + +## Verification +- /smo-dev-guide --topic chain → still resolves correctly +- README install one-liner → still pointing at v1.4.2 (correct tag) +``` + +## Never + +- Never edit `architecture/brd.md` (BRD is source of truth — the doc-sync only validates trace). +- Never delete files (only edits + scaffolds). +- Never commit to main if the merged PR is on a feature branch still being worked on. +- Never bypass branch protection (open the follow-up PR instead). + +## See also + +- `gstack:document-release` (the engine) +- `brd-traceability` skill +- `lessons-manager` skill +- `/smo-ship` (the trigger) +- SOP-22 (lessons promotion), SOP-13 (handover doc discipline) diff --git a/plugins/smorch-dev/commands/smo-handover.md b/plugins/smorch-dev/commands/smo-handover.md index d7a5fd0..1a1e0dc 100644 --- a/plugins/smorch-dev/commands/smo-handover.md +++ b/plugins/smorch-dev/commands/smo-handover.md @@ -7,24 +7,35 @@ description: Generate dev→QA handover brief from SOP-13 template. Auto-fills P **Pillar:** SOP-13 (Lana Handover Protocol) **When:** After `/smo-score` returns 92+. Before Lana starts QA. +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Pre-handover verification | `superpowers:verification-before-completion` | Always (during `--validate`) | + +L2 wrappers: `handover-generator` auto-fills the brief from PR + score + BRD; `brd-traceability --emit-scenarios` seeds 4 scenarios per AC; `qa-handover-scorer` is consumed downstream by Lana. + ## Workflow -1. Invoke `handover-generator` skill -2. Auto-fill from git + filesystem: +1. **L2 handover-generator** skill auto-fills brief from git + filesystem: - PR number, URL, branch - BRD ACs covered (from @AC-N.N test tags) - Env vars (diff `.env.example`) - Score report (latest `docs/qa-scores/`) - Rollback command (from `.smorch/project.json` → `deploy.rollback_template`) - - Scenario stubs: invoke `brd-traceability --emit-scenarios` → 4 stubs per AC (happy/empty/error/edge) embedded in Section 2 -3. Prompt dev to fill: + - Scenario stubs: invoke **L2 brd-traceability --emit-scenarios** → 4 stubs per AC (happy/empty/error/edge) embedded in Section 2 +2. Prompt dev to fill: - Replace every `{stub — ...}` placeholder in Section 2 with real test steps - Known issues + untested areas - Seed data + feature flags -4. Dev reviews + signs off -5. Commit to `docs/handovers/YYYY-MM-DD-PR-{n}-handover.md` -6. Run `--validate` → check all 5 sections have content, PR URL resolves, no `{stub — ...}` placeholders remain in Section 2 -7. Run `--notify` → Telegram ping to Lana with link +3. Dev reviews + signs off +4. Commit to `docs/handovers/YYYY-MM-DD-PR-{n}-handover.md` +5. **`--validate`** — the real gate, layered: + - **L3 superpowers:verification-before-completion** — sanity-check that the brief actually reflects the merged code: PR URL resolves, score file referenced exists, `@AC-N.N` test tags claimed in Section 1 exist in the test files, rollback command in Section 5 is the canonical one from `.smorch/project.json` + - All 5 sections have substantive content (each ≥3 lines) + - No `{stub — ...}` placeholders remain in Section 2 + - Reject with specific reason on any failure (e.g., `validate FAIL: Section 1 claims AC-1.3 but tests/draft.test.ts has no @AC-1.3 tag`) +6. `--notify` → Telegram ping to Lana with link (only after validate passes) ## Arguments diff --git a/plugins/smorch-dev/commands/smo-ship.md b/plugins/smorch-dev/commands/smo-ship.md index 62deb23..4e7bc8e 100644 --- a/plugins/smorch-dev/commands/smo-ship.md +++ b/plugins/smorch-dev/commands/smo-ship.md @@ -14,6 +14,7 @@ description: Merge + tag (NOT deploy). Final gate before server push. 92+ score | Perf regression gate | `gstack:benchmark` (via `/smo-benchmark`) | If any UI/API code touched | | PR template + create | `gstack:ship` | Always | | Branch finish flow | `superpowers:finishing-a-development-branch` | Always (merge / PR / keep / discard decision) | +| Post-merge docs sync | `gstack:document-release` (via `/smo-document --auto`) | Always, after successful merge | L2 wrappers: smo-scorer composite ≥ 92 + hat floor ≥ 8.5, qa-handover-scorer ≥ 80, brd-traceability AC = 100%, elegance-pause block in last commit. @@ -51,14 +52,16 @@ Fire these 6 read-only gate checks **concurrently**. Each emits `GATE_{name}: PA 3. **L3 superpowers:finishing-a-development-branch** — present merge / PR / keep / discard decision flow; verify clean test baseline 4. On merge: tag release per semver (auto-bump patch unless --minor/--major) 5. Push tag -6. Append to `docs/ships/trend.csv` +6. **`/smo-document --auto`** — post-merge docs sync (wraps `gstack:document-release`). Reads the merged diff, syncs README/CLAUDE.md/CHANGELOG/ARCHITECTURE to match what shipped. Trivial changes (<20 lines, README only) commit direct to main; non-trivial open a follow-up PR. Suppress with `--skip-document` (rare). +7. Append to `docs/ships/trend.csv` (now includes `doc_lines_changed`, `doc_follow_up_pr` columns) -**Order:** gates → build → push branch → gstack:ship creates PR → /smo-review-pr (external review) → if 0 blockers → finishing-a-development-branch merges. /smo-review-pr is INSIDE the ship flow, not a separate manual step. +**Order:** gates → build → push branch → gstack:ship creates PR → /smo-review-pr (external review) → if 0 blockers → finishing-a-development-branch merges → tag pushed → /smo-document --auto syncs docs. Every step is INSIDE the ship flow, not a separate manual ceremony. ## Arguments - `--minor` / `--major` — version bump override (default: patch) - `--skip-deploy` — just merge + tag, don't queue deploy (rare; most PRs deploy after ship) +- `--skip-document` — skip the post-merge `/smo-document --auto` step (rare; for branches where docs are intentionally hand-curated) ## Gate (blocks if any fail) diff --git a/plugins/smorch-dev/commands/smo-simplify.md b/plugins/smorch-dev/commands/smo-simplify.md new file mode 100644 index 0000000..96d4291 --- /dev/null +++ b/plugins/smorch-dev/commands/smo-simplify.md @@ -0,0 +1,112 @@ +--- +description: Code-quality fix loop. Wraps gstack:simplify. Reviews changed code for reuse, quality, efficiency — then fixes. Auto-invoked by /smo-bridge-gaps when Engineering Q4/Q5 are dragging. +allowed-tools: Bash, Read, Write, Edit +--- + +# /smo-simplify + +**Scope:** review the current diff for reuse / quality / efficiency, apply mechanical fixes, surface judgment calls. +**When:** auto-invoked by `/smo-bridge-gaps` when the lowest hat is Engineering and Q4 (code quality) or Q5 (elegance) are the dragging questions. Manually callable any time during `/smo-code` or pre-`/smo-score`. + +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Simplify engine | `gstack:simplify` | Always | + +L2 wrappers: `elegance-pause` runs once on the resulting diff (re-asks "would I write this again?"); `cost-tracker` flags if simplification touches Claude/OpenAI call sites (token cost delta). + +## Workflow + +1. Determine scope: current branch diff vs base (default `main`) OR `$ARGUMENTS` file/glob. +2. **L3 gstack:simplify** scans the diff for: + - Duplicated logic that should reuse an existing utility + - Dead branches / unreachable code + - Inefficient patterns (N+1 queries, unnecessary re-renders, large bundle imports) + - Over-abstraction (premature interfaces, single-use helpers) + - Under-abstraction (3+ near-identical blocks) +3. Categorize findings: + - **AUTO** — safe mechanical fix (apply immediately, commit-staged) + - **REVIEW** — judgment call (present options, prompt user) + - **DEFER** — non-trivial refactor (skip in this PR, append to follow-up issue) +4. Apply AUTO fixes. Re-run tests after each batch (≤5 fixes per batch). +5. Prompt user for REVIEW items (only if not invoked with `--auto`). +6. **L2 elegance-pause** runs once on the resulting diff. +7. **L2 cost-tracker** — if Claude/OpenAI call sites were touched, recompute the projected cost delta + annotate. +8. Write summary to `docs/simplifications/YYYY-MM-DD-{branch}.md`. + +## Arguments + +| Flag | Effect | +|---|---| +| `$ARGUMENTS` | Optional file/glob to scope (default: full branch diff vs base) | +| `--auto` | Invoked by `/smo-bridge-gaps`. Non-interactive — applies AUTO, defers REVIEW. | +| `--dry-run` | Report findings, don't write | +| `--strict` | Treat REVIEW items as DEFER (only apply AUTO) — for pre-/smo-ship safety | + +## Auto-invocation contract (from /smo-bridge-gaps) + +When `/smo-bridge-gaps` identifies Engineering hat as the lowest scorer AND Q4 or Q5 are the dragging questions, it invokes `/smo-simplify --auto`: +- Non-interactive: applies AUTO, defers REVIEW, never blocks +- Writes evidence file regardless +- Returns summary to bridge-gaps for the re-score prediction + +The dev sees inline: +``` +🔧 /smo-bridge-gaps — targeting Engineering (current: 7.5) + Q4 (code quality), Q5 (elegance) are dragging +🔍 /smo-simplify --auto + AUTO (applied): + - src/lib/draft.ts:42 → reuse `getRetryConfig` (was duplicated 3x) + - src/lib/draft.ts:88 → kill dead branch (unreachable since #142 merge) + - src/components/Draft.tsx:34 → use `useMemo` for tracked deps + REVIEW (deferred — surface to dev): + - src/api/draft/route.ts → consider extracting Claude call to lib/claude-client.ts + DEFER (out of scope this PR): + - app/admin/* → repeated form-field pattern (5 places) — refactor to component + Re-score prediction: Eng 7.5 → 9.0 (composite 87 → 93) +``` + +## Output + +`docs/simplifications/YYYY-MM-DD-{branch}.md`: + +```markdown +# Simplify — feat/draft-endpoint — 2026-04-29 14:30 + +**Triggered by:** /smo-bridge-gaps --auto +**Scope:** branch diff vs main (12 files) + +## AUTO (applied, 3) +- src/lib/draft.ts:42 → reuse `getRetryConfig` from src/lib/http.ts (deleted 18 lines) +- src/lib/draft.ts:88 → removed dead branch (unreachable since #142) +- src/components/Draft.tsx:34 → useMemo for `dependencies` (perf) + +## REVIEW (deferred to dev, 1) +- src/api/draft/route.ts:67 → Claude call inline (consider extracting to lib/) + Options: (A) extract now (~20 lines refactor), (B) defer to next sprint + +## DEFER (out of scope, 1) +- app/admin/* → repeated form-field pattern (5 places) — separate refactor PR + +## elegance-pause verdict +- "Would I write this again?" — YES after AUTO fixes. Cleaner. + +## cost-tracker delta +- Claude API call sites: unchanged (no API surface touched) + +## Re-score prediction +Engineering 7.5 → 9.0 (composite 87 → 93) +``` + +## Never + +- Never apply REVIEW items in `--auto` mode (defeats the dev's judgment opportunity). +- Never silently delete tests (if a test becomes "unused," it's a sign — flag it as REVIEW, don't remove). +- Never simplify across module boundaries without elegance-pause (could break encapsulation). + +## See also + +- `gstack:simplify` (the engine) +- `elegance-pause`, `cost-tracker` (L2 wrappers) +- `/smo-bridge-gaps` (the auto-trigger) diff --git a/plugins/smorch-dev/commands/smo-verify.md b/plugins/smorch-dev/commands/smo-verify.md new file mode 100644 index 0000000..0e39128 --- /dev/null +++ b/plugins/smorch-dev/commands/smo-verify.md @@ -0,0 +1,130 @@ +--- +description: Live verification before commit. Wraps gstack:verify + gstack:run + gstack:browse. Auto-invoked by /smo-code between impl and commit. Enforces ~/.claude/CLAUDE.md QA-DISCIPLINE rule (exercise failure paths, not just happy paths). +allowed-tools: Bash, Read, Write +--- + +# /smo-verify + +**Scope:** launch the app, exercise the change in a real environment, capture evidence. +**When:** auto-invoked by `/smo-code` after the green TDD step, before commit. Manually callable any time to re-verify a change. + +**Why this exists:** type-check + unit tests + `200 OK` smoke is NOT enough (lesson from April 28 — 4 escaped bugs to Lana in 24h, all preventable). Real production paths involve: real DB writes, real network failures, real race conditions, real memory limits. This command exercises them. + +## L3 cascade (hard-required, see SOP-36) + +| Step | L3 Skill | When | +|------|----------|------| +| Launch the app | `gstack:run` | Always (matched to project type) | +| Live behavior check | `gstack:verify` | Always | +| Headless UI driver | `gstack:browse` | If `has_ui=true` in `.smorch/project.json` | + +L2 wrappers: `cost-tracker` checks any Claude/OpenAI calls made during verification stay under budget; `brd-traceability` confirms the verified scenario maps to the `@AC-N.N` tag from the current TDD step. + +## Workflow + +1. Read `.smorch/project.json`: + - `project_type` → drives `gstack:run` invocation (Next.js / FastAPI / CLI / library) + - `has_ui` → drives `gstack:browse` engagement + - `risk_surfaces` → drives which failure paths are mandatory (auth → "missing bearer / wrong bearer"; payments → "decline / partial capture"; migrations → "rollback drill") +2. **L3 gstack:run** — launches the app in the project's dev mode (already aware of Next.js vs FastAPI vs CLI vs library per its own detection). +3. **L3 gstack:verify** — exercises the change: + - Happy path (matches the TDD test that just went green) + - Mandatory failure paths from `risk_surfaces` (above) + - At least 1 edge case (empty input / extreme value / concurrent invocation) +4. **L3 gstack:browse** (if `has_ui=true`) — takes screenshot of the changed surface, diffs against baseline if one exists at `docs/verifications/baseline/`. +5. **L2 cost-tracker** — any Claude/OpenAI calls during verify are counted; flag if PR pushes monthly spend >120% of baseline. +6. **L2 brd-traceability** — confirms the verified scenarios map back to the AC tags being implemented. +7. Aggregate to `docs/verifications/YYYY-MM-DD-{branch}.md`: + - Happy: PASS / FAIL with evidence (log excerpt, screenshot) + - Each failure path: PASS / FAIL with evidence + - Edge case: PASS / FAIL + - Cost delta vs baseline +8. **Hard gate:** if any mandatory scenario FAILs → commit blocked. Operator must fix the underlying code (not the verification) before re-attempting commit. + +## Arguments + +| Flag | Effect | +|---|---| +| `$ARGUMENTS` | Optional explicit scenario name (default: all per `risk_surfaces`) | +| `--auto` | Invoked by `/smo-code`. Non-interactive. Hard-gates the commit on FAIL. | +| `--skip-ui` | Skip `gstack:browse` even if `has_ui=true` (rare; for API-only PRs) | +| `--no-block` | Report only, don't block commit (use for exploratory work, NOT before /smo-ship) | +| `--update-baseline` | After successful verification, refresh `docs/verifications/baseline/` (use on intentional UI changes) | + +## Auto-invocation contract (from /smo-code) + +`/smo-code` step 3 (per AC, after green TDD step) invokes `/smo-verify --auto`: +- Non-interactive +- Hard-gates the commit (blocking) +- Writes evidence file regardless of outcome + +The dev sees inline in `/smo-code` output: +``` +✓ AC-1.1 test passing (green) +🔍 /smo-verify --auto + ✓ Happy: PASS (live) + ✓ Missing bearer → 401 + toast (live) + ✓ Wrong bearer → 403 (live) + ✓ Empty input → "—" returned, no crash (live) + 📷 Screenshot: docs/verifications/2026-04-29-feat-draft.png +✓ Proceeding to commit +``` + +Or on failure: +``` +✓ AC-1.1 test passing (green) +🔍 /smo-verify --auto + ✓ Happy: PASS (live) + ❌ Missing bearer → 500 + crash (expected: 401) +🛑 Commit blocked. Fix src/api/draft.ts:42 (missing auth guard) then re-run /smo-code. +``` + +## Output + +`docs/verifications/YYYY-MM-DD-{branch}.md`: + +```markdown +# Verification — feat/draft-endpoint — 2026-04-29 14:23 + +**Triggered by:** /smo-code --auto +**Project type:** nextjs (has_ui=true) +**Risk surfaces:** auth, claude-api + +## Scenarios + +### Happy path ✓ +- Setup: bearer valid, prompt "summarize this doc" +- Live: returned 200, draft generated 1.2s +- Evidence: docs/verifications/2026-04-29-feat-draft-happy.png + +### Failure: missing bearer ✓ +- Live: 401 returned, toast "Sign in required" + +### Failure: claude API timeout (forced via network throttle) ✓ +- Live: 30s AbortController fired, toast "Service unavailable" + +### Edge: 10,000 char input ✓ +- Live: gracefully truncated, no crash + +## Cost-tracker +- Claude calls: 3 (≈$0.04) +- Cumulative this PR: $0.18 (baseline avg $0.21 → -14%) ✓ + +## BRD traceability +- AC-1.1, AC-1.2 covered ✓ + +## Verdict: PASS — commit proceeds +``` + +## Never + +- Never `--no-block` in `/smo-code` (defeats the purpose). +- Never claim "verified" without exercising the failure paths in `risk_surfaces`. +- Never count a unit test as verification (unit ≠ live). + +## See also + +- `gstack:verify`, `gstack:run`, `gstack:browse` (the engines) +- `cost-tracker`, `brd-traceability` (L2 wrappers) +- `/smo-code` (the trigger) +- `~/.claude/CLAUDE.md` § QA-DISCIPLINE (the rule this enforces) diff --git a/plugins/smorch-dev/commands/smorch-dev-start.md b/plugins/smorch-dev/commands/smorch-dev-start.md index 155e487..0d2f8d5 100644 --- a/plugins/smorch-dev/commands/smorch-dev-start.md +++ b/plugins/smorch-dev/commands/smorch-dev-start.md @@ -38,6 +38,11 @@ description: One-command bootstrap + enforcement for any SMOrchestra session. De - Verify local is not >1 day behind origin (drift flag). - Verify no uncommitted changes >1 hour old (L-009 flag). - Surface open PRs targeting current branch. +- **L3 safety-mode suggestion** (additive, never auto-engages): + - **Profile = `prod-server`** → output banner: `🛡️ Suggest: /careful — destructive ops warned (rm -rf, DROP TABLE, force-push). Override per-prompt.` + - **Project `.smorch/project.json:risk_surfaces[]` matches `auth`, `payments`, or `migrations`** → output banner: `🛡️ Suggest: /guard — careful mode + edits restricted to current directory. Frees you to focus without straying.` + - **cwd matches `auth/`, `payments/`, `migrations/`, `secrets/`, or `.env*`** even without project-level risk_surfaces → same `/guard` suggestion + - These are SUGGESTIONS only — `/smorch-dev-start` never auto-engages safety modes (engineer's call). Suggestion text shows the exact slash command to type. **Layer 3 — Project enforcement (is this repo Boris-compliant?)** Skipped if outside a project or `--skip-project` passed. Per active repo: diff --git a/plugins/smorch-dev/skills/dev-guide-router/SKILL.md b/plugins/smorch-dev/skills/dev-guide-router/SKILL.md index aef8bf1..3a2cf4d 100644 --- a/plugins/smorch-dev/skills/dev-guide-router/SKILL.md +++ b/plugins/smorch-dev/skills/dev-guide-router/SKILL.md @@ -1,7 +1,7 @@ --- name: dev-guide-router description: | - In-session guide router for smorch-dev + smorch-ops. Resolves topic queries from /smo-dev-guide. Covers command surface (17 commands + verb boundaries), daily chain + wall-clock targets, scoring gates (92/8.5), SOP-13 handover rubric, QA workflow + MENA/rollback gates, architecture (plugins + overlay + 2-tier skills + marketplace), infrastructure (4 servers + Tailscale + install profiles + cron sync + drift detection), deploy paths (PM2 vs docker-compose), incident response, secrets rotation, hooks, validators, lessons. Context-aware "next" resolves to a single command based on current repo state. Read-only. Never hallucinates commands or SOPs. + In-session guide router for smorch-dev + smorch-ops. Resolves topic queries from /smo-dev-guide. Covers command surface (22 commands incl. L3 wrappers + verb boundaries), daily chain + wall-clock targets, scoring gates (92/8.5), SOP-13 handover rubric, QA workflow + MENA/rollback gates, architecture (plugins + overlay + 2-tier skills + marketplace), infrastructure (4 servers + Tailscale + install profiles + cron sync + drift detection), deploy paths (PM2 vs docker-compose), incident response, secrets rotation, hooks, validators, lessons. v1.6.0 L3 wrapper topics: verify, simplify, canary, document, cso. Context-aware "next" resolves to a single command based on current repo state. Read-only. Never hallucinates commands or SOPs. --- # dev-guide-router — In-Session Guide @@ -30,8 +30,8 @@ One topic per invocation. If two are obviously linked, end with `also see: {topi Bootstrap & gates: `start` · `overview` · `next` · `chain` · `score` · `handover` · `qa` · `ship` · `deploy` -L3 cascade (gstack + superpowers): -`l3` · `worktree` · `benchmark` · `review-pr` +L3 cascade (gstack + superpowers) — v1.5 + v1.6: +`l3` · `worktree` · `benchmark` · `review-pr` · `verify` · `simplify` · `canary` · `document` · `cso` Architecture: `architecture` · `plugins` · `overlay` · `skills` · `marketplace` · `validators` · `hooks` @@ -101,17 +101,27 @@ also see: next · chain · score ## Topic: `overview` ``` -smorch-dev + smorch-ops — 19 commands, 2 plugins, 0 overlap. +smorch-dev + smorch-ops — 22 commands, 2 plugins, 0 overlap. Session bootstrap (run FIRST every session): /smorch-dev-start — machine + context + project + input-quality (4 layers) GREEN/YELLOW/RED gate, --fix for auto-heal + v1.6: Layer 2 suggests /careful (prod-server) or /guard + (auth/payments/migrations risk surfaces) -Workflow (smorch-dev, 12 commands): +Workflow (smorch-dev, 15 commands): /smorch-dev-start /smo-plan /smo-code /smo-score /smo-bridge-gaps /smo-handover /smo-qa-handover-score /smo-qa-run /smo-ship /smo-triage /smo-retro /smo-dev-guide (this) + /smo-worktree /smo-benchmark /smo-review-pr (v1.5 L3 wrappers) + +v1.6 L3 wrappers (smorch-dev, +5): + /smo-verify live verification before /smo-code commit (auto) + /smo-simplify code-quality fix loop (auto from /smo-bridge-gaps) + /smo-document post-ship docs sync (auto from /smo-ship) + /smo-canary post-deploy regression watch (auto from /smo-deploy) + /smo-cso security audit — nightly + monthly + post-incident Ops (smorch-ops, 7 commands): /smo-deploy /smo-rollback /smo-drift /smo-health @@ -1011,6 +1021,9 @@ Wiring map — which L1 command invokes which L3 skill: /smo-code → superpowers:test-driven-development (per AC) → superpowers:subagent-driven-development (>1 file) → superpowers:dispatching-parallel-agents (3+ investigations) + → /smo-verify --auto (live verify before commit, v1.6) + + /smo-verify → gstack:run + gstack:verify + gstack:browse (v1.6) /smo-triage → gstack:investigate → superpowers:systematic-debugging @@ -1018,6 +1031,7 @@ Wiring map — which L1 command invokes which L3 skill: /smo-review-pr → superpowers:requesting-code-review → superpowers:receiving-code-review (on feedback) → gstack:review (optional pre-landing) + → /security-review (built-in, on --security flag) /smo-benchmark → gstack:benchmark @@ -1026,24 +1040,39 @@ Wiring map — which L1 command invokes which L3 skill: Architecture → gstack:plan-eng-review UX → gstack:plan-design-review Engineering → superpowers:requesting-code-review + + /smo-simplify --auto (v1.6, on Q4/Q5) QA → gstack:qa (extended) + /smo-simplify → gstack:simplify (v1.6) + + /smo-handover → superpowers:verification-before-completion (v1.6, in --validate) + /smo-qa-run → gstack:qa (or qa-only) → gstack:browse (UI scenarios) /smo-ship → gstack:ship (PR template) → superpowers:finishing-a-development-branch (merge flow) + → /smo-document --auto (post-merge docs sync, v1.6) + + /smo-document → gstack:document-release (v1.6) /smo-retro → gstack:retro - /smo-deploy → gstack:canary (post-deploy) + /smo-deploy → /smo-canary --auto (post-deploy, wraps gstack:canary, v1.6) + + /smo-canary → gstack:canary (v1.6) + + /smo-cso → gstack:cso (--daily / --full / --post-incident) (v1.6) /smo-incident → superpowers:systematic-debugging (root-cause phase) + /smorch-dev-start Layer 2 → suggests /careful (prod-server profile) (v1.6) + → suggests /guard (risk_surfaces: auth/payments/migrations) + Anti-bloat rule (SOP-36): L2 skills MUST NOT reimplement L3 work. Pre-commit guard: scripts/check-no-l2-reimplementation.sh. -also see: chain · ship · sop-36 +also see: chain · ship · sop-36 · verify · simplify · canary · document · cso ``` --- @@ -1124,6 +1153,155 @@ also see: l3 · score · ship --- +## Topic: `verify` (v1.6) + +``` +/smo-verify — live verification before commit. Auto-invoked by /smo-code +between the green TDD step and commit. Hard-gates the commit on failure. + +Engines: gstack:run + gstack:verify + gstack:browse (if has_ui=true). + +Exercises: + - Happy path (matches the TDD test) + - Mandatory failure paths from .smorch/project.json:risk_surfaces[] + (auth → missing/wrong bearer; payments → decline/partial; migrations → rollback drill) + - At least 1 edge case + +Why this exists: unit tests passing + 200 OK smoke is NOT enough. Real +production paths involve real DB writes, real network failures, real race +conditions, real memory limits (lesson April 28: 4 escaped bugs to Lana in +24h, all preventable by live verification). + +Output: docs/verifications/YYYY-MM-DD-{branch}.md + screenshot if has_ui. + +Flags: --auto (from /smo-code, non-interactive, blocks commit on fail), + --no-block (report only — never use before /smo-ship). + +Enforces ~/.claude/CLAUDE.md § QA-DISCIPLINE. + +also see: l3 · code · qa +``` + +--- + +## Topic: `simplify` (v1.6) + +``` +/smo-simplify — code-quality fix loop. Auto-invoked by /smo-bridge-gaps +when Engineering hat is the lowest scorer AND Q4 (quality) or Q5 (elegance) +are the dragging questions. Manually callable any time. + +Engine: gstack:simplify. + +Categorizes findings: + AUTO safe mechanical fixes (apply immediately) + REVIEW judgment calls (present options, prompt user) + DEFER non-trivial refactor (skip this PR, append to issue) + +L2: elegance-pause runs once on the resulting diff. cost-tracker flags if +Claude/OpenAI call sites were touched. + +Output: docs/simplifications/YYYY-MM-DD-{branch}.md with re-score prediction. + +Flags: --auto (from /smo-bridge-gaps, applies AUTO defers REVIEW), + --strict (treat REVIEW as DEFER — pre-/smo-ship safety). + +also see: l3 · bridge-gaps · score +``` + +--- + +## Topic: `canary` (v1.6) + +``` +/smo-canary — post-deploy regression watch. Auto-invoked by /smo-deploy +after a clean health check. Manually callable for pre-major-event watch. + +Engine: gstack:canary. + +Window: 30 min default (configurable per .smorch/project.json:canary). +Watches: console errors, page failures, Core Web Vitals vs baseline, +periodic screenshots every 5 min. + +L2: drift-detector cross-checks server HEAD mid-window. incident-runbook +auto-stubs a SEV2 on breach. + +On breach: + - Stops watching (one alert) + - Auto-triggers /smo-rollback --auto (production targets default ON) + - Telegram SEV2 with screenshot + canary report attached + +Output: docs/canary/YYYY-MM-DD-{tag}.md (or async append on breach). + +Flags: --auto (from /smo-deploy, background-runs, Telegram-reports), + --window N (override window minutes), + --no-rollback (alert without rolling back — for planned promotions), + --update-baseline (refresh perf baseline after intentional change). + +also see: l3 · deploy · rollback · benchmark +``` + +--- + +## Topic: `document` (v1.6) + +``` +/smo-document — post-ship docs sync. Auto-invoked by /smo-ship after a +successful merge. Manually callable after manual merges / hotfixes. + +Engine: gstack:document-release. + +Updates: README.md, CLAUDE.md, ARCHITECTURE.md, CONTRIBUTING.md, CHANGELOG, +TODOs swept, VERSION file bumped (if present). + +L2: brd-traceability re-checks BRD AC table reflects current @AC-N.N tags +(catches stale ACs post-refactor). lessons-manager appends new lessons. + +Categorization: + Trivial (<20 lines, README only) → commit direct to main + Non-trivial → open follow-up PR (titled "docs: sync to {tag}") + +Flags: --auto (from /smo-ship), --dry-run, --force-pr (always open PR), + --skip-lessons (skip lessons-manager step). + +Output: docs/ships/{tag}-doc-sync.md + trend.csv row. + +also see: l3 · ship · sop-22 +``` + +--- + +## Topic: `cso` (v1.6) + +``` +/smo-cso — Chief Security Officer audit. Wraps gstack:cso. + +Cadence: + --daily (CI cron, nightly, 8/10 confidence gate — zero noise on green tree) + --full (manual, monthly, 2/10 bar — secrets archaeology, deps supply chain, + CI/CD security, LLM/AI security, skill supply chain, OWASP, STRIDE) + --post-incident (narrow scan focused on incident-touched surfaces) + +L2 cross-checks: secrets-manager validates rotation SLA on any secret-related +finding; drift-detector validates infra-drift correlation on infra findings. + +Gate per mode: + --daily ≥1 BLOCKER → CI fails + Telegram SEV2 + --full any SEV1 → Telegram SEV1 + auto-stub /smo-incident + --post-incident any unmitigated recurrence → SEV1 + block until sign-off + +Output: docs/security/YYYY-MM-DD-{mode}.md + trend.csv. + +Founding context: April 18 perfctl malware incident — three weeks of work lost. +This cadence exists to prevent the next one. + +Flags: --no-block (incident triage only), --target (scope to one). + +also see: l3 · incident · secrets · sop-10 · l-001 +``` + +--- + ## Topic: `parity` (server-side parity — SOP-37) ``` diff --git a/plugins/smorch-dev/templates/smorch-project.json.template b/plugins/smorch-dev/templates/smorch-project.json.template index a66fb81..f830d3e 100644 --- a/plugins/smorch-dev/templates/smorch-project.json.template +++ b/plugins/smorch-dev/templates/smorch-project.json.template @@ -36,5 +36,20 @@ "overrides": { "_notes": "Optional path to rubric overrides for smo-scorer. Files live in .smorch/overrides/*.json." + }, + + "has_ui": false, + "_has_ui_notes": "v1.6+. Set true for projects with browser UI. Drives gstack:browse engagement in /smo-verify and /smo-qa-run, and design-review invocation in QA. Default false.", + + "risk_surfaces": [], + "_risk_surfaces_notes": "v1.6+. Array of risk categories the project touches: 'auth', 'payments', 'migrations', 'pii', 'secrets'. Drives mandatory failure-path coverage in /smo-verify, /guard suggestion in /smorch-dev-start, and risk_tier=high routing in /smo-review-pr. Default empty.", + + "performance_critical_paths": [], + "_performance_critical_paths_notes": "v1.6+. Array of file globs (e.g., ['src/lib/draft.ts', 'app/api/**']) whose changes trigger gstack:benchmark in /smo-score. Default empty (only /smo-benchmark + /smo-ship GATE_benchmark check perf).", + + "canary": { + "window_minutes": 30, + "auto_rollback": true, + "_notes": "v1.6+. /smo-canary --auto config. window_minutes: how long to watch post-deploy. auto_rollback: trigger /smo-rollback on breach (default true for production targets, set false for staging if rollback would cause more damage than the breach)." } } diff --git a/plugins/smorch-ops/commands/smo-deploy.md b/plugins/smorch-ops/commands/smo-deploy.md index 2b917e6..159ac61 100644 --- a/plugins/smorch-ops/commands/smo-deploy.md +++ b/plugins/smorch-ops/commands/smo-deploy.md @@ -11,9 +11,9 @@ description: SSH deploy via ecosystem.config.js. Project-aware (reads .smorch/pr | Step | L3 Skill | When | Owner | |------|----------|------|-------| -| Post-deploy canary | `gstack:canary` | Always after step 6 (health 200 OK) | gstack | +| Post-deploy canary | `gstack:canary` (via `/smo-canary --auto`) | Always after step 6 (health 200 OK) | gstack | -L2: deploy-pipeline runbook owns SSH/PM2/drift. L3 owns post-deploy regression watch. +L2: deploy-pipeline runbook owns SSH/PM2/drift. L3 owns post-deploy regression watch (via `/smo-canary` wrapper which also handles drift cross-check + incident-runbook escalation). ## Workflow @@ -31,21 +31,16 @@ L2: deploy-pipeline runbook owns SSH/PM2/drift. L3 owns post-deploy regression w - `pm2 reload {pm2_process_name}` 5. Wait 10s 6. Hit `/api/health` endpoint → verify 200 + commit SHA matches deploy -7. **L3 gstack:canary** — post-deploy regression watch (60-300s window): - - Console errors via browse daemon - - Performance regressions vs last deploy baseline - - Page failures on top-3 routes - - Compares against baseline in `docs/canary/baseline.json` - - If any tracked metric regresses or any page errors → trigger /smo-rollback --auto + SEV2 alert +7. **`/smo-canary --auto`** — post-deploy regression watch (default 30-min window, configurable per `.smorch/project.json:canary.window_minutes`). Wraps `gstack:canary` and adds L2 drift-detector cross-check mid-window + L2 incident-runbook auto-stub on breach. Runs in background — `/smo-deploy` returns control immediately; Telegram reports outcome at window end. On any breach → auto-trigger `/smo-rollback --auto` (per project config, default ON for production targets). 8. Run `/smo-drift --post` (confirm clean) -9. Log deploy to `docs/deploys/YYYY-MM-DD-{tag}.md` (includes canary delta) -10. Telegram notify: "✅ {project} v{tag} deployed to {target} — canary clean" +9. Log deploy to `docs/deploys/YYYY-MM-DD-{tag}.md` (canary outcome appended async by `/smo-canary` when watch completes) +10. Telegram notify: "✅ {project} v{tag} deployed to {target} — canary watching (30 min)" ## Failure handling - Step 4 fails (build/pm2) → immediate rollback via `/smo-rollback --auto` - Step 6 fails (health check) → `/smo-rollback --auto` + Telegram SEV2 alert -- Step 7 fails (canary regression) → `/smo-rollback --auto` + SEV2 alert with canary report attached +- Step 7 breach (canary regression mid-window) → `/smo-rollback --auto` + SEV2 alert with canary report attached + auto-stub `/smo-incident` - Step 8 fails (drift detected) → `/smo-rollback --auto` + SEV1 alert (something changed server-side mid-deploy) ## Arguments