Karvey Deploy

Karvey Deploy

Purpose

PHASE 11 of the Karvey Method, between karvey-qa (PHASE 10) and karvey-archive (PHASE 12). It executes the ordered deployment flow (feature branch → dev → PR to master) honoring the team's hard rules to the letter: never commit directly to dev/master, never deploy manually (the deploy is triggered by the pipeline), pull before starting and before each merge/PR, and prod never without explicit human OK.

It runs only after karvey-qa has passed with no open critical/high findings. The central rule is karvey/rules/deploy-workflow.md; follow it exactly.

Execution steps

Step 0 — Pre-checks (release gate)

BEFORE touching git, read:

• docs/spec/changes/{change-id}/spec.json
• docs/spec/project.json

If project.json does not exist, stop and indicate to run karvey-init first (see karvey/rules/project-config.md).

Verify the release gate. If anything fails, STOP and report what is missing. Do not deploy.

1. QA approved with no open critical/high findings.

   • Locate the most recent review document: REVISION_PR_*_{date}.md at the root of each affected repo (ls -t REVISION_PR_*.md | head -1).
   • The karvey-qa security gate must be OK: 0 critical findings and 0 unresolved high findings in the severity table / pre-merge checklist.
   • Confirm QA status in spec.json (approvals.qa / phase).

2. Tests PASS. Review docs/test_evidence.md: there must be entries for the {change-id} with PASS result for the change's tests.

3. CHANGELOG updated in each affected repo (see karvey/rules/changelog-policy.md). For each repo in project.json:repos with changes, verify CHANGELOG.md:

   • Entry for the current version.
   • Responsible human (name + contact) — never empty nor replaced by "AI".
   • AI model that assisted (e.g., Claude Opus 4.8).
   • The why, not just the what.
   • CHANGELOG version matches the project's version file.

If any of these fail, report exactly what is missing and stop. Do not deploy.

Step 1 — Determine repos and order

Read from project.json:

• repos (array, at least 1).
• branch_flow: feature_prefix (default feature/), integration (default dev), production (default master).

If the change touches multiple repos, honor the dependency order declared in architecture.md (e.g., DB → backend → frontend). For each repo, the Step 2 flow is applied in that order.

Record the resolved order before starting.

Step 1.5 — Auto-detection of the deploy platform

Before deploying, confirm how and where each repo is released. If project.json already declares it (deploy.platform, deploy.prod_url, deploy.health_check per repo), use that. If it is not configured, detect it and record it in project.json for future runs.

Detect the platform by evidence in the repo (do not assume):

Discover the production URL and health check:

• Look for the prod URL in project.json:deploy, pipeline variables, README/docs/spec/, or the platform config (e.g., fly.toml, vercel.json).
• Determine the health endpoint: /health, /healthz, /api/health, the frontend's root page, or whatever architecture.md declares. For non-web targets (CLI/API/mobile), the "health check" is the equivalent in the target's actual runtime (see karvey/rules/targets.md).

If the prod URL/health cannot be discovered, do not invent it: record it as pending and ask the user for the data before the prod canary. The hard rule stands: the deploy is triggered by the pipeline, this detection is only to know where to monitor, never to deploy manually.

Record what was detected in project.json:deploy (platform, prod_url, dev_url, health_check) per repo.

Step 2 — Ordered deployment flow (FOR EACH repo)

Apply following karvey/rules/deploy-workflow.md EXACTLY, in the dependency order from Step 1.

2.1 — git pull before starting:

git pull

2.2 — Ensure feature branch. NEVER commit directly to dev/master. Verify you are working on feature/{change-id}:

git branch --show-current   # must be feature/{change-id}

If the feature/{change-id} branch does not exist, stop — karvey-impl should have created it. Do not create it here.

2.3 — Before the merge, pull integration:

git pull origin {integration}     # default: dev

2.4 — Version bump + CHANGELOG BEFORE the push (see karvey/rules/versioning.md and karvey/rules/changelog-policy.md). This is part of the 6-step checklist (Step 3) and is mandatory: NEVER deploy without bumping the version.

1. Determine the semver segment to increment (major.minor.rev) per the nature of the change:
   • major → breaking change (breaks API/contract/schema/behavior compatibility).
   • minor → new backward-compatible feature.
   • rev → fix/adjustment/minor change with no new feature.
2. Version bump in each affected component/repo. Edit the version file per the stack (package.json, pyproject.toml, *.csproj, VERSION, git tags, etc.). If a repo has several deployable components, bump the one of the component that changed.
3. Document in CHANGELOG.md per component AND per repository (changelog-policy.md format): an entry for the new version with the responsible human (name + contact, never empty nor "AI"), the AI model that assisted (e.g., Claude Opus 4.8), and the why of the change (not just the what). Indicate the incremented semver segment and why.
4. (If the repo has a frontend) recommend a version visible in the UI — see Step 2.4-bis.

2.4-bis — Version visible in the front (recommendation). If any target in project.json is web/mobile/desktop with a UI (check project.json:targets), recommend to the user exposing the version in the interface (footer, "About" screen) for visible traceability in production: inject the version at build time (e.g., VITE_APP_VERSION or the stack's equivalent) and show it in a discreet but accessible place. If the version is already visible, just confirm it was updated with the bump.

2.5 — Merge feature → integration:

git checkout {integration}        # dev
git merge feature/{change-id}

2.6 — Push to integration ⇒ triggers DEV pipeline (the deploy is done by the pipeline, NOT manually):

git push origin {integration}     # dev → triggers DEV pipeline

2.7 — Post-deploy canary in DEV (see Step 2-bis): wait for the pipeline to deploy and run the canary loop over the actual DEV runtime (green pipeline build + health monitoring). Do not advance to prod if DEV did not end up healthy or if the canary detects a regression.

2.8 — Before the PR, pull production:

git pull origin {production}      # default: master

2.9 — Create PR dev → master:

gh pr create --base {production} --head {integration} \
  --title "[Deploy] {change-id}" \
  --body "Deploy of {change-id}. QA OK, tests PASS, CHANGELOG updated. Requires human OK to merge to prod."

2.10 — Merge to master ONLY with explicit human OK ⇒ triggers PROD pipeline. Use AskUserQuestion to request explicit prod approval. Without human OK, do not merge. With OK:

gh pr merge --merge          # ⇒ triggers PROD pipeline

2.11 — Post-deploy canary in PROD (see Step 2-bis): after the merge to master, wait for the PROD pipeline and run the canary loop over the actual production runtime (prod_url / health from Step 1.5). It is the direct reinforcement of zero-downtime: if the canary detects a regression, alert and recommend an immediate rollback.

Step 2-bis — Post-deploy canary loop (zero-downtime reinforcement)

Inspired by gstack's /canary and adapted to the target's actual runtime (see karvey/rules/targets.md). It runs after each deploy (in DEV after 2.7 and in PROD after 2.11), pointing at the just-deployed environment (dev_url/prod_url and health from Step 1.5). It watches that the deploy did not degrade the service.

What the loop watches (several iterations, not a single check):

1. Console/log errors — browser console (web, via karvey-browse), runtime/platform logs (Functions, container, etc.). Look for new errors that did not exist before the deploy.
2. Performance regressions — latency/response time of the health and of key endpoints; compare against the pre-deploy baseline. Noticeable degradation = regression.
3. Page/endpoint failures — walk through the change's critical routes/endpoints and the product's main ones; any 5xx, timeout, or broken page counts as a failure.

How to run it:

• Rely on karvey-browse ("get eyes") for the target's runtime: headless browser (web), simulator/device (mobile), HTTP client (API), process/terminal (CLI). It does not assume a browser.
• Repeat the cycle (console → performance → pages/endpoints) over a reasonable window post-deploy (several spaced iterations), not a single shot. Record evidence of each iteration.
• In DEV: if the canary flags a regression, stop and do not advance to prod; fix it first.
• In PROD: if the canary flags a regression, alert immediately and recommend a rollback (revert the merge / deploy the previous version via pipeline). Never leave prod degraded. The rollback is also executed by the pipeline, never manually.

Canary result: OK (no regressions) or REGRESSION (with detail of what failed: console/perf/endpoint). Leave the result recorded for the final output and management.

Step 3 — 6-step checklist (before the push to dev)

From karvey/rules/deploy-workflow.md. Show and verify before the push to dev:

1. Am I on a feature branch? (not dev/master)
2. Did I bump the semver version (major/minor/rev) in each affected component/repo and update CHANGELOG.md per component and per repo? (see versioning.md and changelog-policy.md; if there is a frontend, did I recommend/update the version visible in the UI?) NEVER deploy without bumping the version.
3. Is everything pending committed?
4. Pushed the branch?
5. Merged to dev?
6. Pushed dev?

Only after the 6 → the pipeline deploys dev. For prod, repeat the verification and PR to master with human approval.

Step 4 — Hard rules (NEVER skip)

• NEVER commit directly to dev or master. Always a feature branch.
• NEVER deploy manually. The deploy is triggered by the pipeline (push to dev, merge to master). func azure functionapp publish or manual equivalents are FORBIDDEN.
• pull before starting and before each merge/PR.
• Prod NEVER without explicit human OK. The PR to master is not merged without approval.
• NEVER deploy without bumping the version (semver + CHANGELOG per component and repo).
• Zero downtime: the deployment cannot cause a service outage; the post-deploy canary reinforces this and, on a prod regression, recommends a rollback (via pipeline, never manual).

Step 5 — Record in management

Read management from spec.json.

If management = clickup: create task [Deploy] {change-id} with the 6-step checklist as subtasks and close it on prod confirmation:

clickup_create_task
  name: "[Deploy] {change-id}"
  list_id: "{sprint_list_id}"
  priority: "high"

For each repo, record DEV and PROD deploy status. Close the task on confirming the merge to prod (PROD pipeline OK).

If management = markdown: add an entry in PLAN.md with the deploy status per repo and environment:

## Deploy — {change-id}
| Repo | DEV | PROD |
|------|-----|------|
| {repo1} | ✅ deployed | ⏳ PR open / ✅ merged |
| {repo2} | ... | ... |

Step 6 — Update spec.json

spec.json:
  phase: "deployed"
  approvals.deploy.generated: {YYYY-MM-DD}
  approvals.deploy.approved: {YYYY-MM-DD if there was prod human OK, otherwise null}

Step 7 — Knowledge sync

Run the sync step of karvey/rules/knowledge-sync.md per knowledge_sync in project.json:

• obsidian → sync the modified documents to the vault via the Obsidian MCP (fallback to graphify if it fails).
• graphify → /graphify docs/spec/ --update (if docs/spec/graphify-out/ does not exist, without --update).
• Multi-repo with code changes → graphify also in each affected repo.

Step 8 — Final output

✅ Deploy complete — {change-id}

Repos deployed (in dependency order):
  - {repo1}: v{new_version} · DEV ✅ canary OK  |  PROD {✅ merged, canary OK / ⏳ PR open, awaiting human OK}
  - {repo2}: v{new_version} · DEV ✅ canary OK  |  PROD ...

6-step checklist: verified
QA gate: OK (0 critical, 0 high) · Tests: PASS · Version bumped + CHANGELOG: OK
Deploy platform: {Fly | Render | Vercel | Netlify | Azure | GitHub Actions | ...} · Prod URL: {prod_url}
Post-deploy canary: DEV {OK / REGRESSION} · PROD {OK / REGRESSION → rollback recommended / N/A}
{If there is a frontend} Version visible in UI: {yes / recommended to the user}

Management: {[Deploy] {change-id} in ClickUp | PLAN.md updated}
Knowledge sync: {obsidian | graphify} updated

Next step: /karvey-archive {change-id}

Safety

• NEVER commit directly to dev or master — always a feature branch.
• NEVER deploy manually — func azure functionapp publish and equivalents are forbidden; the deploy is triggered by the pipeline (push dev, merge master).
• pull before starting and before each merge/PR.
• Prod NEVER without explicit human OK — the PR to master is not merged without approval.
• NEVER deploy without bumping the version — semver (major/minor/rev) bumped and CHANGELOG per component and per repo (see versioning.md and changelog-policy.md).
• Zero downtime — the deployment cannot cause a service outage; the post-deploy canary (DEV and PROD) reinforces this and, on a prod regression, recommends a rollback (always via pipeline, never manual).
• Mandatory release gate — without QA OK (0 critical/high), tests PASS, version bumped, and CHANGELOG complete, no deploy happens.
• In multi-repo, honor the dependency order from architecture.md (DB → backend → frontend).

Advance to the next phase

When finishing this phase and having the corresponding approval, actively ask the user: "Shall we advance to the Archive (closure) phase now?"

• If they confirm → run /karvey-archive {change-id}.
• If they prefer to review or adjust first → wait. Advancing is always with the user's OK (the method's gate).
• If you resume in another session, /karvey {change-id} indicates which phase you are in and which one follows.

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md.