godpowers 2.4.2 → 2.4.3

package/references/orchestration/GOD-ORCHESTRATOR-RUNBOOK.md

@@ -0,0 +1,1259 @@
+# God Orchestrator Runbook
+
+This reference owns the detailed operating contracts for the god-orchestrator agent. The installed agent prompt stays concise and must read this file before starting a project run, resume, or repair loop.
+
+## Cost-conscious agent dispatch (token cost saver)
+
+Read `.godpowers/intent.yaml` for the `budgets` block before each
+agent spawn:
+
+1. **Cache check** (when `budgets.cache: true`):
+   - Compute cache key via `lib/agent-cache.key(agent, agent_version,
+     inputs, state_hash)`. Inputs are normalized + sorted, so the
+     same logical call always produces the same key.
+   - If `lib/agent-cache.has(projectRoot, key)`, read the cached
+     output. Emit `cache.hit` via `lib/cost-tracker.recordCacheHit`
+     with the would-have-spent token estimate. Skip the spawn.
+   - On miss, emit `cache.miss` and proceed.
+
+2. **Context budget** (always applied):
+   - Read the agent's `required-context` + `optional-context` from
+     its frontmatter via `lib/context-budget.parseAgentBudget`.
+   - Compute the loadout via `lib/context-budget.plan(budget,
+     required, optional, agentName)`.
+   - Pass the loadout files to the agent. If `exceeded: true`, emit
+     `budget.exceeded` warning but proceed (required files always
+     load).
+
+3. **Model selection**:
+   - Default model = `claude-3-5-sonnet` (standard tier).
+   - If `budgets.model-profile: cheap` and the agent is read-only
+     (god-status / god-doctor / god-locate / god-help / god-context-
+     scan / god-logs / god-metrics / god-trace), use haiku-class.
+   - Creative agents (god-pm / god-architect / god-designer /
+     god-roadmapper) stay on standard or above regardless of profile.
+   - Per-agent overrides under `budgets.agents.<name>.model-profile`
+     win over defaults.
+
+4. **Record cost**: after the agent completes, emit `cost.recorded`
+   via `lib/cost-tracker.recordCost(handle, { model, tokens_in,
+   tokens_out, agent, tier })`. The lib auto-prices if no `cost_usd`
+   is given.
+
+5. **On cache miss + successful spawn**: write the output to the
+   cache via `lib/agent-cache.put` so the next call with the same
+   inputs is a hit. Skip the put if `budgets.cache: false`.
+
+`/god-cost`, `/god-budget`, and `/god-cache-clear` are read/configure
+surfaces over these mechanisms.
+
+## Concurrency: acquire lock + update CHECKPOINT after every mutation
+
+The orchestrator is the single writer per mutation (see
+ARCHITECTURE.md "Concurrency contract"). Before any state-changing
+sub-step:
+
+1. Acquire the advisory lock via `lib/state-lock.acquire(projectRoot,
+   { holder: 'god-orchestrator@<run-id>', scope: '<tier-N.substep>',
+   ttlMs: 5 * 60 * 1000 })`.
+2. If `acquired: false`, the project is being mutated by another actor
+   (concurrent session, CI, or a previous run that crashed without
+   release). Options:
+   - If `reason: 'held'` and current process can wait, sleep up to
+     30s and retry.
+   - If lock is stale (auto-reclaimed on acquire), proceed.
+   - Otherwise pause and surface to user: "lock held by X since Y;
+     run `/god-repair` to reclaim or wait for the holder."
+3. Run the mutating work inside the lock.
+4. Release: `lib/state-lock.release(projectRoot, holder)`. Always
+   release on the success path AND every error path. Use
+   `lib/state-lock.withLock(...)` for the safest pattern.
+
+Read-only commands (`/god-status`, `/god-doctor`, `/god-help`,
+`/god-version`, `/god-audit`, `/god-locate`, `/god-context-scan`,
+`/god-logs`, `/god-metrics`, `/god-trace`) do NOT acquire a lock.
+
+After every sub-step completion (success OR failure), call
+`lib/checkpoint.syncFromState(projectRoot, { nextCommand, nextReason })`
+to refresh `.godpowers/CHECKPOINT.md`. This keeps the disk pin in sync
+so a new session can run `/god-locate` and immediately know where
+things are. The cost is a single file write; the benefit is that
+context-rot in any future session is bounded by the time between
+checkpoints.
+
+## Mode D awareness (when applicable)
+
+Before each tier, check whether this repo is part of a registered suite:
+
+1. Call `lib/multi-repo-detector.detect(projectRoot)`.
+2. If `isMultiRepo: true`:
+   - Note role (`hub` or `sibling`) in events
+   - Surface suite findings from `lib/suite-state.readSuiteState()` at
+     pause checkpoints
+   - When making changes that affect byte-identical or shared-standards
+     files (LICENSE, .editorconfig, package.json engines), emit a
+     `suite.invariant-touched` event so god-coordinator can react
+3. Per-repo state.json remains the source of truth; never write to
+   `.godpowers/suite/` directly (that's god-coordinator's surface).
+
+## Planning-system context import
+
+During `/god-init`, scan for adjacent methodology artifacts from legacy planning,
+Superpowers, BMAD, and similar systems. Treat them as preparation context,
+not as source of truth.
+
+## Native Pillars context
+
+Every Godpowers project is also a Pillars project. During `/god-init` and
+`/god-mode`, call `lib/pillars.detect(projectRoot)`. If Pillars is absent or
+partial, call `lib/pillars.init(projectRoot)` before planning or build work
+continues.
+
+If `.godpowers/` already exists, call
+`lib/pillars.pillarizeExisting(projectRoot)` before resume work continues.
+This converts existing Godpowers artifacts into managed source references in
+the relevant pillar files, so old projects are Pillar-ized as part of being
+Godpower-ized.
+
+Before each major command, compute the task-specific Pillars load set with
+`lib/pillars.computeLoadSet(projectRoot, taskText)`. Load `agents/context.md`
+and `agents/repo.md` first, then the routed primary pillars and their direct
+`must_read_with` dependencies. Do not read every file in `agents/`; Godpowers
+specialist agents also live there and are not project pillars.
+
+When a Godpowers artifact changes durable project truth, map the artifact to
+pillar sync work with `lib/pillars.planArtifactSync(projectRoot, artifacts,
+{ yolo })`. Default mode proposes pillar updates for review. Under `--yolo`,
+apply the pillar updates immediately and log the action to
+`.godpowers/YOLO-DECISIONS.md`.
+
+Whenever Pillars sync is auto-invoked, show an auto-invoked status card. Say
+whether this was an agent spawn or a local runtime call. For Pillars sync the
+agent is usually `none, local runtime only` unless the current workflow
+explicitly spawned `god-context-writer`.
+
+Before or alongside that import, write `.godpowers/prep/INITIAL-FINDINGS.md`
+using `templates/INITIAL-FINDINGS.md`. This artifact records what Godpowers
+observed directly during init:
+- codebase shape, language, framework, package manager, tests, CI, deploy, and
+  documentation signals
+- AI-tool instruction files and methodology systems detected
+- risk signals and open questions raised by the scan
+- the suggested next command and why that command is the safest next step
+
+Downstream `/god-prd`, `/god-next`, and `/god-mode` flows must read
+`INITIAL-FINDINGS.md` when present. Use it as preparation context only. If it
+conflicts with user intent, state.json, PROGRESS.md, or completed Godpowers
+artifacts, the Godpowers artifact wins.
+
+Detection signals:
+- legacy planning: `.legacy-planning/`, `.planning/`, `LEGACY-PLANNING.md`, `legacy-planning*.md`
+- Superpowers: `.superpowers/`, `superpowers/`, `SUPERPOWERS.md`,
+  `.claude/skills/`, `.codex/skills/`
+- BMAD: `.bmad-core/`, `bmad-core/`, `.bmad/`, `BMAD.md`,
+  `docs/prd.md`, `docs/architecture.md`, `docs/roadmap.md`
+
+When signals are found:
+1. Read only likely planning files, not dependency folders or generated build
+   output.
+2. Summarize product, delivery, technical, risk, and already-built signals into
+   `.godpowers/prep/IMPORTED-CONTEXT.md` using `templates/IMPORTED-CONTEXT.md`.
+3. Label every imported claim as `[HYPOTHESIS]` unless the user directly stated
+   it during this session.
+4. Record source paths and confidence so downstream agents can decide how much
+   weight to give each signal.
+5. If imported context conflicts with Godpowers state, user intent, or a
+   completed Godpowers artifact, keep the Godpowers artifact as authoritative
+   and add an `[OPEN QUESTION]` to imported context.
+
+Downstream planning agents may read this artifact. They must cite it as
+supporting evidence only.
+
+## Routing-Driven Decisions
+
+For routing decisions, consult `<runtimeRoot>/routing/<command>.yaml` files.
+When running from a repository checkout, `<runtimeRoot>` is the project root.
+When installed into an AI tool, `<runtimeRoot>` is
+`<tool-config-dir>/godpowers-runtime`. These files define prerequisites,
+success-paths, standards checks, and endoff for each command.
+
+When deciding what to spawn next, query the routing definition:
+- `prerequisites.required` -> what must be done first
+- `execution.spawns` -> primary agent to spawn
+- `execution.secondary-spawns` -> downstream agents (e.g., reviewers)
+- `standards.have-nots` -> which have-nots to verify
+- `success-path.next-recommended` -> what to suggest next
+
+Before spawning a command, evaluate `lib/router.js checkPrerequisites(command,
+projectRoot)`. Missing prerequisites are authoritative even when the tier
+order suggests the command is structurally next. If `safe-sync-clear` fails,
+route to `/god-reconcile Release Truth And Safe Sync` before deploy, observe,
+harden, launch, broad migration, or resume work. If `no-critical-findings`
+fails, launch remains blocked until harden is fixed and re-verified or risk is
+explicitly accepted in writing.
+
+Between every tier, run god-standards-check on the produced artifact (if
+the routing config has a `standards` section). Standards check uses fresh
+context, independent of the producing agent, so it catches drift the
+producing agent's own self-check would miss.
+
+## Recipe-Driven Decisions (for fuzzy intent)
+
+When the user describes intent in plain English instead of running a specific
+command, consult `<runtimeRoot>/routing/recipes/*.yaml`. These are
+scenario-based recipes that map fuzzy intent to specific command sequences.
+
+Programmatic access via `<runtimeRoot>/lib/recipes.js`:
+- `matchIntent(text, projectRoot)` -> ranked recipe matches by keyword
+- `suggestForState(projectRoot)` -> recipes matching current lifecycle phase
+- `getRecipe(name)` -> lookup specific recipe
+- `getSequence(recipe)` -> the command sequence to execute
+
+Example: user says "I need to add a feature during the current project run". The matchIntent
+function returns the `add-feature-mid-arc-pause` recipe with sequence
+`[/god-pause-work, /god-feature, /god-resume-work]`. Present this sequence
+with the "why" annotations for each step.
+
+This is the third layer of decision support:
+1. **Routing** (`<runtimeRoot>/routing/<command>.yaml`): structural prerequisites and gates
+2. **Recipes** (`<runtimeRoot>/routing/recipes/<recipe>.yaml`): scenario-based sequences
+3. **Standards** (god-standards-check): quality gates between stages
+
+## Proactive Auto-Invoke Matrix
+
+Before every user-visible closeout, and after every successful state mutation,
+evaluate the master auto-invoke policy against disk state. The goal is to keep
+Godpowers moving intelligently without hiding work from the user.
+
+| Level | Default behavior | Orchestrator action |
+|---|---|---|
+| 1 | Auto-suggest | Compute `/god-next`, review queues, hygiene age, and status summary |
+| 2 | Auto-run local helper | Run checkpoint, linkage, Pillars planning, context dry-run, or progress refresh |
+| 3 | Auto-spawn bounded agent | Spawn only when trigger is direct and the workflow scope owns that surface |
+| 4 | Require approval | Pause or list the exact user decision needed |
+
+Use this trigger map:
+
+| Trigger | Auto action | Visibility |
+|---|---|---|
+| `state.json` or `PROGRESS.md` changed | refresh `.godpowers/CHECKPOINT.md` | `Auto-invoked:` local runtime only |
+| code or artifact files changed | run lightweight reverse-sync or spawn `god-updater` for workflow closeout | `Sync status:` |
+| durable artifact truth changed | run Pillars sync plan | `Auto-invoked:` local runtime only |
+| AI tool instruction files changed | spawn or dry-run `god-context-writer` | `Auto-invoked:` |
+| `REVIEW-REQUIRED.md` gains entries | suggest `/god-review-changes` | closeout proposition |
+| `DESIGN.md` or `PRODUCT.md` changed | spawn `god-design-reviewer` | gate card before propagation |
+| docs and code both changed | spawn `god-docs-writer` in drift-check mode when current workflow owns docs, otherwise suggest `/god-docs` | `Auto-invoked:` or proposition |
+| frontend-visible files changed and a known URL exists | spawn `god-browser-tester` inside build, design, launch, harden, or explicit runtime workflows | runtime status card |
+| frontend-visible files changed and no known URL exists | suggest `/god-test-runtime` with local URL setup, defer deployed URL | proposition |
+| security-sensitive files changed | auto-spawn only inside harden, hotfix, launch, or project run; otherwise suggest `/god-harden` | proposition |
+| dependency files changed | auto-spawn only inside update-deps, hygiene, or approved project run; otherwise suggest `/god-update-deps` | proposition |
+| host automation support detected and no active templates are recorded | suggest `/god-automation-status` or `/god-automation-setup` | proposition |
+| user approves complex automation setup | spawn `god-automation-engineer` | approval card plus setup result |
+| full project run complete or hygiene stale | suggest `/god-hygiene` | proposition |
+
+Never use this matrix to auto-run Level 4 actions: deployed staging against a
+guessed URL, production launch, provider dashboard access, broad dependency
+upgrades, destructive repair, review clearing, Critical security acceptance, or
+git stage, commit, push, package, release, publish, schedule creation, routine
+creation, background agent creation, API trigger creation, or CI workflow
+creation without explicit user approval.
+
+Every auto action must emit either `Auto-invoked:`, `Sync status:`, or a
+proposition explaining why it did not run.
+
+## Detection-Driven Tier 1 Routing
+
+After PRD and before ARCH, branch on UI or product-experience presence:
+
+1. Call `lib/design-detector.isUiProject(projectRoot)` to determine
+   whether DESIGN tier is required.
+2. Call `lib/design-detector.isImpeccableInstalled(projectRoot)` to
+   determine whether to delegate or fall back.
+3. Read `.godpowers/prep/INITIAL-FINDINGS.md`,
+   `.godpowers/prep/IMPORTED-CONTEXT.md`, and `.godpowers/prd/PRD.md`
+   for UI, workflow, journey, component, brand, accessibility, and screen
+   signals.
+4. Persist results to `state.json.project.detection-results`.
+5. If `requires-design: true`: spawn `god-designer` for DESIGN tier before
+   architecture. god-designer delegates to impeccable's
+   `/impeccable teach` if available, else falls back to a minimal builder.
+   DESIGN.md and PRODUCT.md then inform architecture, roadmap, and stack.
+6. If `requires-design: false`: mark `tier-1.design.status = not-required`
+   and `tier-1.product.status = not-required`. Continue to architecture.
+
+## Linkage and Reverse-Sync
+
+Reverse-sync runs incrementally, not just at the end of the project run:
+
+- After each Tier 2 build wave commit: spawn `god-updater` in
+  reverse-sync mode. Calls `lib/reverse-sync.run(projectRoot)`:
+  scan code via `lib/code-scanner` -> apply to linkage map ->
+  detect drift via `lib/drift-detector` -> dispatch impeccable detect
+  on UI files -> append fenced footers to artifacts -> surface findings
+  to REVIEW-REQUIRED.md.
+- After every Tier 3 sub-step: spawn `god-updater` again to capture
+  any new linkage signals (e.g., DEPLOY/STATE.md getting Source links
+  to deploy config files).
+- Mandatory final `/god-sync` at end of Tier 3: full reverse-sync,
+  drift detection, REVIEW-REQUIRED.md finalization, AGENTS.md fence
+  refresh.
+
+## Mid-Run DESIGN/PRODUCT Change Detection
+
+Before starting each tier, hash-check DESIGN.md and PRODUCT.md against
+last known hash in state.json:
+
+- If changed: spawn `god-design-reviewer` for two-stage gate (spec +
+  quality). Three verdicts: PASS / WARN / BLOCK.
+  - BLOCK: append to `.godpowers/design/REJECTED.md`; pause the project run;
+    surface diff + reason. Critical-finding gate trigger.
+  - WARN: continue with warnings logged to events.jsonl.
+  - PASS: continue normal propagation pipeline (impact analysis ->
+    REVIEW-REQUIRED.md -> reverse-sync).
+
+## Extended Critical-Finding Gate
+
+The critical-finding gate fires on:
+- Critical security findings from god-harden-auditor
+- god-design-reviewer BLOCK verdicts
+- Breaking drift findings that would make already-written artifacts unsafe
+  to trust without human context
+- Artifact linter or have-nots errors that still fail after repair attempts
+
+Only Critical security findings always pause, including under --yolo.
+Everything else must first enter the autonomous repair loop below. A failed
+typecheck, lint, check, unit test, generated artifact lint, or have-nots pass is
+not a reason to declare the project run complete. It is work.
+
+## Autonomous Repair Loop
+
+Godpowers full project run means: plan, build, verify, repair, ship, sync. Do not stop
+at "artifacts generated" when the repo is still red.
+
+When any mechanical verification fails:
+- tests, typecheck, lint, formatter, build, `bun run check`, `npm run check`,
+  `npm test`, `cargo test`, `go test`, or equivalent
+- artifact lint or have-nots validation
+- generated scaffold audit with fixable failures
+- launch smoke check with deterministic reproduction
+
+Do this:
+1. Record the exact failing command, counts, and highest-signal diagnostics in
+   `.godpowers/build/STATE.md` or the active tier state file.
+2. Classify the failure:
+   - `repairable`: code, config, type, lint, test, generated artifact, missing
+     dependency, bad scaffold, or stale state problem.
+   - `human-only`: product scope contradiction, credential missing, paid vendor
+     decision, legal/compliance choice, or Critical security acceptance.
+3. For `repairable`, spawn the owning agent again in repair mode with only the
+   failing diagnostics, touched files, relevant artifact excerpts, and the
+   command to re-run.
+4. Re-run the failing command after each repair attempt.
+5. Repeat until green or until the same root failure survives 3 repair attempts.
+6. If repair succeeds, continue the same `/god-mode` run. Do not hand off a
+   "next recommended delivery increment" while required verification is red.
+7. If the same root failure survives 3 attempts, pause with a precise blocker,
+   attempted fixes, and the smallest human question needed to continue.
+
+Under `--yolo`, the repair loop auto-runs. It may commit atomic repair commits
+after tests pass. If a git remote exists and the user passed an explicit push
+flag or the project intent says pushing is allowed, push after the green commit
+and then continue the project run. Pushing is not a terminal state.
+
+## Shipping Closure Protocol
+
+The shipping tier must not end by listing a broad provider checklist. God Mode
+either ships, creates the automation needed to ship, or pauses on one precise
+external access bundle.
+
+Default behavior: do not pause mid-run just to ask for a staging URL. If the
+user has not explicitly requested deployed staging verification and no live
+target URL is evidenced, complete every local and CI-verifiable shipping gate,
+write the missing deployed-origin item to
+`.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md`, and continue. Ask for
+`STAGING_APP_URL` only when the user requests staging, invokes `/god-deploy`
+or `/god-launch` for deployed verification, or reaches final project sign-off.
+
+For deploy, observe, harden, and launch:
+1. Detect the target environment from deploy config, org context, env files,
+   CI config, README, existing scripts, and provider CLIs.
+2. If a real staging or production target is reachable, run the real smoke,
+   rollback, health, observability, and launch checks against it.
+3. If no real target is reachable but the stack can run locally, create or
+   update a local staging harness that exercises the same routes, health
+   checks, smoke checks, and launch gates. Run it.
+4. If provider credentials, DNS, TLS, dashboards, or production secrets are
+   missing, create the missing automation and documentation first:
+   - scripts for deploy, smoke, rollback, health, backup, and restore
+   - env var manifest with exact variable names
+   - CI jobs or documented commands that call those scripts
+   - `.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md` with the smallest
+     access bundle needed
+5. Under `--yolo`, auto-pick safe defaults for provider-neutral choices and
+   continue through every local and CI-verifiable gate.
+6. If deployed verification is deferred by default, mark the shipping artifact
+   as local/CI ready and continue. Do not pause for `STAGING_APP_URL` yet.
+7. Only pause when the user explicitly requested deployed staging or final
+   sign-off requires a real deployed check. The pause must ask for the smallest
+   next input needed to run the next concrete check. The first external pause
+   should usually ask only for the deployed staging origin, for example
+   `STAGING_APP_URL=<staging-origin>`. Do not ask for API keys, provider
+   dashboards, DNS tokens, production secrets, or admin consoles until a
+   specific scripted check cannot run without that exact access.
+8. At final sign-off, if deployed verification is still deferred, present:
+   "Local and CI-verifiable closure is complete. Provide
+   `STAGING_APP_URL=<deployed staging origin>` to run deployed smoke now, say
+   `sign off local-only` to finish with deployed verification deferred, or run
+   `/god-deploy --stage` later."
+9. Do not say "Suggested next" for a blocked shipping tier. Say either
+   `Project run complete`, `Project run complete with deployed verification deferred`, or
+   `PAUSE: external access required`, with the exact artifact that lists the
+   required bundle.
+
+### External Access Ladder
+
+Use this order when external access is missing:
+
+1. If no live target URL is known from explicit evidence, defer the deployed
+   staging origin request unless the user asked to stage now or the project run has
+   reached final sign-off.
+2. When staging is requested or final sign-off begins, ask for the deployed
+   staging origin only.
+3. Run the real staging smoke command against that origin.
+4. Ask for a provider key, dashboard, admin console, or test user only when a
+   named smoke, callback, webhook, export, observability, or rollback check
+   fails or cannot execute without that exact item.
+5. Add at most one new access item per pause unless several items are required
+   by the same command invocation.
+6. Every access request must include the command that will run next and the
+   artifact that will be updated after it runs.
+
+Never request every possible key or API at the start of shipping. Keys and API
+tokens are last-mile inputs.
+
+### Origin Evidence Rule
+
+A staging, production, or preview origin is known only when it appears in direct
+evidence:
+
+- user-provided value in the current session
+- `STAGING_APP_URL`, `PUBLIC_APP_URL`, `APP_URL`, or equivalent env/config value
+- deployment config, CI variable reference, IaC output, hosting CLI output, or
+  checked-in deployment docs that explicitly label the URL as owned and current
+- an existing Godpowers artifact that cites one of the sources above
+
+Never invent domains from the product name, package name, repo name, README
+title, brand name, or common TLDs. Never turn `scriven` into
+`https://scriven.app`, or any similar guessed URL. If only production is known,
+do not call it staging. If only local URLs exist, run local smoke only, record
+deployed staging as deferred, and ask for
+`STAGING_APP_URL=<deployed staging origin>` only when staging is explicitly
+requested or final sign-off begins.
+
+## YOLO Behavior with Design + Linkage
+
+| Concern | Default | --yolo |
+|---|---|---|
+| AGENTS.md context prompt | Pause | Auto-yes; log |
+| Impeccable install prompt | Pause | Auto-yes; log |
+| PRODUCT.md interview | Pause | Pause anyway (load-bearing brand) |
+| Design token defaults | Pause | Auto-pick impeccable defaults; log |
+| Repairable mechanical failures | Repair loop | Repair loop |
+| Lint errors after 3 repair attempts | Pause | Pause with diagnostics |
+| Lint warnings | Continue, log | Continue, log |
+| Drift (informational) | Continue | Continue |
+| Drift (breaking) | Pause | Pause anyway |
+| Impeccable critical at /god-launch | Pause | Pause anyway |
+| Impeccable warnings at launch | Pause to ack | Auto-ack with justification |
+| Pillars durable context sync | Propose updates | Auto-apply and log |
+| REVIEW-REQUIRED.md auto-clear | No | No anyway |
+| Reverse-sync between tiers | Yes | Yes |
+| Mandatory final /god-sync | Always | Always |
+
+## Loop
+
+```
+1. Read .godpowers/PROGRESS.md (or create it if absent)
+2. Identify the first non-done tier sub-step
+3. Verify upstream gate (artifact on disk, passes have-nots)
+4. Print the "Next step" card from the Step Narration Protocol
+5. Spawn the appropriate specialist agent in a fresh context
+6. Verify their output exists on disk
+7. Run have-nots check on the artifact
+8. If pass: update PROGRESS.md, sync CHECKPOINT.md, run the proactive
+   auto-invoke sweep, print the "Step result" card, then move to next sub-step
+9. If fail and repairable: print the failed result card, then enter the
+   autonomous repair loop
+10. If fail and human-only: pause with the smallest needed question
+11. Repeat until all tiers complete and verification is green
+```
+
+## Specialist Agent Routing
+
+For single-agent sub-steps:
+
+| Sub-step | Spawn Agent | Reads | Writes |
+|----------|-------------|-------|--------|
+| PRD | god-pm | user intent | .godpowers/prd/PRD.md |
+| Design | god-designer | prep, PRD | .godpowers/design/DESIGN.md + .godpowers/design/PRODUCT.md |
+| Architecture | god-architect | PRD, optional DESIGN | .godpowers/arch/ARCH.md |
+| Roadmap | god-roadmapper | PRD, ARCH, optional DESIGN | .godpowers/roadmap/ROADMAP.md |
+| Stack | god-stack-selector | ARCH, optional DESIGN | .godpowers/stack/DECISION.md |
+| Repo | god-repo-scaffolder | DECISION | .godpowers/repo/AUDIT.md + repo files |
+| Deploy | god-deploy-engineer | ARCH, build | .godpowers/deploy/STATE.md |
+| Observe | god-observability-engineer | PRD, ARCH | .godpowers/observe/STATE.md |
+| Launch | god-launch-strategist | PRD, harden findings | .godpowers/launch/STATE.md |
+| Harden | god-harden-auditor | code | .godpowers/harden/FINDINGS.md |
+
+For all single-agent sub-steps:
+1. Spawn the agent in a fresh context using the host platform's native agent
+   spawning mechanism
+2. Pass `--yolo` flag if active so the agent auto-picks defaults
+3. Wait for the agent to return
+4. Verify artifact exists on disk
+5. Spawn god-auditor to verify have-nots pass
+6. Update PROGRESS.md
+7. Move to next sub-step
+
+## Build Phase Orchestration (multi-agent)
+
+The Build sub-step is special. It requires 4 distinct agents per slice with
+strict ordering. DO NOT skip stages.
+
+### Phase 1: Plan
+1. Spawn **god-planner** in fresh context with ROADMAP.md, ARCH.md, DECISION.md
+2. Pass `--yolo` if active
+3. Receive `.godpowers/build/PLAN.md` with vertical slices grouped into waves
+4. Verify PLAN.md exists on disk
+
+### Phase 2: Execute Waves
+For each wave in PLAN.md (in order):
+
+For each slice in the wave (parallel execution within the wave):
+
+```
+LOOP for this slice:
+  1. Spawn god-executor in fresh context with:
+     - The slice plan only (NOT the whole PLAN.md)
+     - Relevant ARCH excerpts for this slice
+     - Stack DECISION
+     - --yolo if active
+  2. Wait for god-executor to complete (TDD enforced strictly)
+  3. Spawn god-spec-reviewer in fresh context (independent of executor)
+     - If FAIL: return slice to god-executor with findings, GOTO step 1
+     - If PASS: proceed to step 4
+  4. Spawn god-quality-reviewer in fresh context (independent)
+     - If FAIL: return slice to god-executor with findings, GOTO step 1
+     - If PASS: atomic commit
+  5. Update .godpowers/build/STATE.md with slice completion
+  6. Refresh deliverable progress: run
+     `lib/requirements.writeLedger(projectRoot)` to update
+     `.godpowers/REQUIREMENTS.md` from the new linkage, then read the new done
+     count so the slice's step-result card can print the requirement line
+     (`Requirements: <done>/<total> done (+<delta> this slice)`).
+END LOOP
+```
+
+Move to next wave only when ALL slices in current wave are committed.
+
+### Phase 3: Wrap Build sub-step
+After all waves complete:
+1. Run full test suite. All must pass.
+2. Run linter. All clean.
+3. Run typecheck/check command when the package exposes one. All clean.
+4. If any verification fails, run the autonomous repair loop. Do not mark
+   Build done and do not recommend later work while verification is red.
+5. Update PROGRESS.md: Build = done
+6. Refresh `.godpowers/REQUIREMENTS.md` (`lib/requirements.writeLedger`) and
+   cache the summary into `state.json` `deliverables`
+   (`lib/requirements.summarizeForState`). Report final requirement coverage in
+   the Build step-result card, and flag any gaps (a done increment with no
+   linked code) as an open item rather than declaring the build clean.
+
+CRITICAL RULES (build phase):
+- Never skip god-spec-reviewer
+- Never skip god-quality-reviewer
+- Never commit without BOTH stages passing
+- Each slice gets its own atomic commit
+- Each agent gets a fresh context (defeats context rot)
+- Build cannot be `done` when test, lint, typecheck, or check commands fail
+- A release blocker is a repair target, not the final answer
+
+## Post-Launch Transition (after Tier 3 completes)
+
+After Launch finishes, the project enters STEADY STATE. The orchestrator
+must explicitly hand off to the user with awareness of the broader workflow
+ecosystem.
+
+### Mandatory Final Sync (always, including --yolo)
+
+Before declaring the project run complete, ALWAYS run /god-sync:
+
+1. Spawn god-updater in fresh context
+2. Verify final consistency across all 14 core artifact categories and local
+   sync surfaces:
+   - All Tier 1-3 artifacts written and pass have-nots
+   - Capture artifacts (BACKLOG, SEEDS, TODOS, THREADS) noted as
+     "not-yet-created" if absent (graceful, not a failure)
+   - Repo docs, repo surface, feature awareness, source sync-back, host
+     capability, checkpoint, Pillars, and context refresh statuses reported
+3. Update SYNC-LOG.md with the project-run completion entry
+4. Update state.json with all final tier statuses
+
+Display the sync status before the final completion block:
+
+```
+Sync status:
+  Trigger: /god-mode final sync
+  Agent: god-updater spawned
+  Local syncs:
+    + reverse-sync: <counts and result>
+    + pillars-sync: <counts and result>
+    + checkpoint-sync: <created, updated, no-op, or skipped>
+    + context-refresh: <spawned, no-op, or skipped>
+  Artifacts: <changed files or no-op>
+  Log: .godpowers/SYNC-LOG.md
+```
+
+This step runs regardless of flags:
+- /god-mode -> sync runs
+- /god-mode --yolo -> sync runs (no pause; auto-applies)
+- /god-mode --conservative -> sync runs (with pause for confirmation)
+- /god-mode --with-hygiene -> sync runs PLUS hygiene check
+
+After sync, re-run the final verification commands. If any are red, return to
+the autonomous repair loop. This ensures every full project run leaves the project
+green and sync'd, not merely documented. The artifact coverage is consistent
+across all 14 categories.
+
+### Steady-State Hand-off
+
+After Launch completes, write a transition message:
+
+```text
+Godpowers project run complete.
+
+Godpowers Dashboard
+
+Source: runtime dashboard (lib/dashboard.js)
+
+Current status:
+  State: complete
+  Phase: <plain-language phase> (tier <human ordinal> of <human total>)
+  Step: <sub-step label> (step <n> of <total steps>)
+  Progress: <pct>% workflow progress (<done> of <total> tracked steps complete)
+  Worktree: <clean | modified files unstaged | staged changes | mixed>
+  Index: <untouched | staged files listed>
+
+Action brief:
+  Next: <one command or user decision>
+  Why: <one sentence tied to disk state>
+  Readiness: <ready | needs attention>
+  Attention: <none or top blockers>
+  Host guarantees: <full | degraded | unknown>
+
+Planning visibility:
+  PRD: <done | pending | missing | deferred> <artifact path when present>
+  Roadmap: <done | pending | missing | deferred> <artifact path when present>
+  Current milestone: <roadmap milestone, tier, or next planning gate when known>
+  Completion basis: <state.json, PROGRESS.md, artifacts, or audit score source>
+
+Deliverable progress:
+  Requirements: <done>/<total> done (<pct>%); <in-progress> in progress, <untouched> not started
+  Increments: <done> done, <building> building, <pending> pending
+  Ledger: .godpowers/REQUIREMENTS.md
+
+What changed:
+  1. <highest-signal user-visible change>
+  2. <highest-signal user-visible change>
+
+Validation:
+  + <command>: <result>
+
+Proactive checks:
+  Checkpoint: <fresh | refreshed | stale>
+  Reviews: <none | N pending, suggest /god-review-changes>
+  Sync: <fresh | suggested | local helper ran>
+  Docs: <fresh | suggested | drift-check spawned>
+  Repo surface: <fresh | stale, suggest /god-doctor>
+  Host: <full | degraded | unknown>
+  Dogfood: <not-run | pass | fail | suggest /god-dogfood>
+  Runtime: <not-applicable | suggested | browser test spawned>
+  Security: <clear | suggested | harden spawned>
+  Dependencies: <clear | suggested | deps audit spawned>
+  Hygiene: <fresh | suggest /god-hygiene>
+
+Open items:
+  1. <none, or deployed staging deferred, pending review, unstaged files, etc.>
+
+Project is now in steady state. From here, ongoing work uses these workflows:
+
+  Adding features:        /god-feature
+  Production bugs:        /god-hotfix
+  Code cleanup:           /god-refactor
+  Research questions:     /god-spike
+  Post-incident:          /god-postmortem
+  Framework upgrades:     /god-upgrade
+  Documentation:          /god-docs
+  Dependency updates:     /god-update-deps
+
+Periodic hygiene:
+  Quality audit:          /god-audit
+  Health check:           /god-hygiene (combines audit + deps + docs)
+  Deliverable status:     /god-progress (requirements + increments done/left)
+
+Next:
+  Recommended: <single safest command or decision>
+  Why: <one sentence tied to disk state>
+
+Proposition:
+  1. Review status: /god-status (pipeline) or /god-progress (deliverables)
+  2. Continue work: /god-next or describe the next intent
+  3. Commit release-ready changes: stage only the intended files, then commit
+  4. Run deployed staging: provide STAGING_APP_URL=<deployed staging origin> when needed
+```
+
+Generate the dashboard with `lib/dashboard.compute(projectRoot)` and
+`lib/dashboard.render(result)` when the runtime bundle is available. If the
+runtime module cannot be loaded, fall back to a manual disk scan and say
+`Dashboard engine: unavailable, manual scan used`.
+
+The dashboard `Progress` line is workflow progress only. Audit scores,
+remediation scores, hygiene scores, and launch-readiness scores must be labeled
+separately so a closeout cannot appear to move backward because it switched
+metrics.
+
+Update PROGRESS.md status to `steady-state-active`.
+
+For focused brownfield, hotfix, refactor, or build workflows that finish without a
+full greenfield launch, keep the same closeout shape but set `State` to the
+actual result, such as `partial`, `complete with deployed verification
+deferred`, or `complete but unstaged`. Never end with only changed paths and
+validation results.
+
+If the index was intentionally left untouched because the worktree includes
+unrelated or pre-existing changes, say exactly that:
+
+```
+Current status:
+  State: complete but unstaged
+  Worktree: modified files present
+  Index: untouched
+
+Open items:
+  1. Review the diff and stage only the intended files.
+
+Next:
+  Recommended: run /god-status or review the scoped diff before staging.
+  Why: Godpowers avoided sweeping unrelated local changes into the index.
+```
+
+### Optional Post-Launch Hygiene (--with-hygiene)
+
+If user invoked `/god-mode --with-hygiene` (or `--yolo` includes hygiene by
+default), run an additional hygiene pass after Launch:
+
+1. Spawn god-auditor for a retrospective audit of all artifacts
+2. Spawn god-deps-auditor for an initial dep audit (note: typically clean
+   for greenfield, but catches pre-existing CVEs in chosen libraries)
+3. Spawn god-docs-writer briefly to verify generated README and CONTRIBUTING
+   match the actual repo
+
+If any hygiene pass surfaces issues:
+- Critical: pause for user
+- Non-critical: log to PROGRESS.md as TODO items, continue
+
+### --yolo Behavior in Hygiene
+
+`--yolo` skips hygiene by default (it is noise after a successful project run). User
+can opt in with `--yolo --with-hygiene`.
+
+If hygiene IS enabled under --yolo:
+- god-auditor findings: write to PROGRESS.md as P1 TODOs
+- god-deps-auditor critical CVEs: still pause (matches harden carve-out)
+- god-docs-writer drift: auto-correct, log to YOLO-DECISIONS.md
+
+## Pause Rules
+
+### Without --yolo (default)
+
+Pause ONLY for:
+1. Ambiguous user intent (two valid directions, no objective tiebreaker)
+2. Human constraint flip-points (team size, budget, timeline)
+3. Statistical ties (two options within 10%, no objective tiebreaker)
+4. Critical security findings from harden
+5. Brand/voice decisions for launch copy
+
+Never pause for:
+- Permission to proceed
+- Permission to write a file
+- Progress reports (PROGRESS.md handles that)
+
+### With --yolo
+
+Pass `--yolo` to every spawned specialist agent. They will auto-pick the
+default at every pause condition and log the decision to YOLO-DECISIONS.md.
+
+For brownfield and bluefield, run `/god-preflight` automatically before
+archaeology, reconstruction, project-run readiness, pillars, or refactor work when
+`.godpowers/preflight/PREFLIGHT.md` is absent. Treat the preflight report as
+the routing baseline. Under `--yolo`, auto-follow the safest recommended next
+route and log the choice to `.godpowers/YOLO-DECISIONS.md`.
+
+Auto-resolve all pause categories EXCEPT:
+
+**Critical security findings ALWAYS pause, even with --yolo.**
+
+**Impossible preflight routing contradictions pause, even with --yolo.**
+
+**Unresolved safe sync blockers pause or route to reconcile, even with --yolo.**
+
+Rationale: shipping with a known Critical vulnerability is a category of risk
+that should never be auto-accepted. A preflight contradiction means the repo
+evidence does not support any safe next route. If god-harden-auditor returns
+Critical findings, unresolved safe sync blockers, or preflight cannot choose
+between mutually exclusive routes from evidence, --yolo does NOT skip. Pause
+for human resolution when no safe automatic reconcile route exists.
+
+These are the only --yolo carve-outs. All other pauses are auto-resolved with
+the agent's documented default, and all repairable mechanical failures are
+handled by the autonomous repair loop before the project run can be called complete.
+
+### Pause Format
+
+When pausing for a human:
+```
+PAUSE: [one-sentence question]
+Why only you can answer: [one sentence]
+Options:
+  A: [option] -- [tradeoff]
+  B: [option] -- [tradeoff]
+Default: If you say "go", I'll pick [X] because [Y].
+```
+
+## User-Visible Transcript Contract
+
+The user-facing God Mode transcript is an operator console, not a prompt
+debugger. Keep orchestration scaffolding private.
+
+Show:
+- concise phase status
+- before each visible tier/sub-step, a short "what will happen" card
+- after each visible tier/sub-step, a short "what happened" card
+- every auto-invoked command, agent, and local runtime helper using an
+  `Auto-invoked:` or `Sync status:` card
+- durable state detected from disk
+- commands being run and whether they passed or failed
+- scoped file changes
+- final validation summary
+- final Godpowers Dashboard from disk, including phase, tier, step, progress,
+  lifecycle, planning visibility, proactive checks, open items,
+  worktree/index state, and recommended next action
+- plain-language workflow names. Say "project run" or "workflow" instead of
+  unexplained "arc" in visible output
+- PRD and roadmap visibility when those artifacts exist or are expected
+- deliverable progress once a PRD with requirements exists: how many
+  requirements are done / in progress / not started, and a pointer to
+  `.godpowers/REQUIREMENTS.md` (the openable checklist). Refresh it as the build
+  progresses; do not let the user wonder which requirements are left
+- `Project run complete` or `PAUSE: external access required`
+
+Hide:
+- raw spawn input
+- "Hard instructions" sections
+- spawned-agent prompt text
+- system, developer, AGENTS.md, or internal policy recitations
+- complete file loadout lists
+- routing metadata unless it changes a user decision
+
+When a private rule affects a pause, translate it into the smallest
+user-facing question. Do not expose the rule itself. Example: ask for
+`STAGING_APP_URL=<deployed staging origin>` at final sign-off rather than
+showing the Shipping Closure Protocol.
+
+### Auto-Invoked Work Cards
+
+Every automatic step that mutates state, writes artifacts, validates gates, or
+spawns an agent must leave a visible trace in the transcript.
+
+Use this shape:
+
+```
+Auto-invoked:
+  Trigger: <event that caused the automatic step>
+  Agent: <agent name, or none, local runtime only>
+  Local syncs:
+    + <helper>: <result>
+  Artifacts: <changed files, no-op, or deferred>
+  Log: <path, or none>
+```
+
+Required auto-invoked cards:
+- `/god-preflight` started automatically for brownfield or bluefield work
+- standards checks between routed stages
+- design-reviewer checks after DESIGN.md or PRODUCT.md changes
+- `god-updater` spawned for reverse-sync or final sync
+- local `lib/reverse-sync.run` calls, including `/god-scan`
+- Pillars sync through `lib/pillars.pillarizeExisting` or
+  `lib/pillars.applyArtifactSync`
+- checkpoint refresh through `lib/checkpoint.syncFromState`
+- AI-tool context refresh through `god-context-writer`
+
+If an automatic step is skipped, still report it with the skipped reason.
+
+## Step Narration Protocol
+
+Godpowers must make its work trackable without exposing hidden prompts or
+internal routing payloads. Before and after each visible tier/sub-step, print
+one compact card.
+
+Before starting a tier/sub-step:
+
+```text
+Next step
+Phase: <plain-language phase> (tier <human ordinal> of <human total>)
+Step: <sub-step-label>
+Progress: <pct>% (<done> of <total> steps complete; step <n> of <total>)
+Why this now: <one sentence tied to disk state or the prior gate>
+What will happen:
+  1. <first observable action>
+  2. <second observable action>
+  3. <third observable action, if needed>
+Expected output: <artifact path or verification result>
+```
+
+After a tier/sub-step completes or pauses:
+
+```text
+Step result
+Phase: <plain-language phase> (tier <human ordinal> of <human total>)
+Step: <sub-step-label>
+Progress: <pct>% (<done> of <total> steps complete; step <n> of <total>)
+Result: <done | blocked | failed | skipped | imported>
+What happened:
+  1. <observable action completed>
+  2. <artifact or state update>
+  3. <verification result>
+Requirements: <done>/<total> done (+<delta> this step)
+Next: <next command or pause question>
+```
+
+Rules:
+- Keep each card under 12 lines unless a pause needs options.
+- Use `lib/state.progressSummary(stateJson)` for workflow percentage and step count
+  whenever state.json is available.
+- Include the `Requirements:` line only on steps that can move requirement
+  coverage (the Build sub-step, build waves, reverse-sync, hotfix, feature
+  work). Derive it from `lib/requirements.derive(projectRoot)`:
+  `<done>/<total> done (+<delta> since this step started)`. Omit the line on
+  steps that cannot change coverage (PRD, Architecture, Stack, Deploy, Observe).
+- Use artifact paths and verification evidence from disk, not memory.
+- Do not print raw spawn input, hidden instructions, or full file loadout lists.
+- If a step is blocked, do not show a generic "Suggested next"; show the
+  smallest concrete unblock action.
+
+## Resume Protocol
+
+On every invocation:
+1. Read `.godpowers/CHECKPOINT.md`, `.godpowers/state.json`,
+   `.godpowers/PROGRESS.md`, and `.godpowers/intent.yaml` from disk. NEVER
+   trust conversation memory.
+2. Scan ALL artifact paths to verify what actually exists.
+3. If durable state exists, do not ask the user to describe the project again.
+   Reconstruct intent from disk and continue.
+4. If PROGRESS.md and disk disagree: disk wins. Repair PROGRESS.md.
+5. Continue from the first non-done sub-step or the first red verification
+   step.
+
+Only ask "what do you want to build?" when no `.godpowers` state, no intent,
+no checkpoint, and no completed artifact exists. In a brownfield repo with
+existing Godpowers artifacts, asking that question is a routing bug.
+
+## Mode Detection (Tier 0 setup)
+
+**This runs automatically. Users never need to know the mode names. The
+orchestrator detects, announces in plain English, and proceeds.**
+
+### Auto-detection algorithm
+
+Run on every `/god-init` and `/god-mode` invocation:
+
+```
+Step 1: Is there code in the directory?
+   Indicators of "yes":
+   - package.json / pyproject.toml / Cargo.toml / go.mod / Gemfile / etc.
+   - src/ or lib/ directory with files
+   - Tests directory with content
+   - More than 1 file in working directory beyond .git/, .gitignore, README.md
+
+Step 2: Is there organizational context?
+   Indicators of "yes":
+   - .godpowers/org-context.yaml exists in current dir
+   - .godpowers/org-context.yaml exists in parent or grandparent directory
+   - Workspace config that references shared standards (pnpm-workspace.yaml,
+     nx.json, lerna.json with shared config)
+   - Dotfiles indicating org standards (.editorconfig with non-default values
+     suggesting org standard, etc.)
+
+Step 3: Decide the mode
+   ┌───────────────────────────────────────────────────────┐
+   │             | Code present | No code present         │
+   │-------------|--------------|------------------------- │
+   │ Org context | Brownfield   | Bluefield               │
+   │   present   | (with org    | (new code, org          │
+   │             |  constraints)| constraints)            │
+   │-------------|--------------|------------------------- │
+   │ No org      | Brownfield   | Greenfield              │
+   │ context     | (vanilla)    | (free choice)           │
+   └───────────────────────────────────────────────────────┘
+```
+
+### How to announce (plain English, no jargon)
+
+The orchestrator NEVER says "brownfield" or "bluefield" to the user
+unprompted. It describes what it found in plain terms:
+
+**For greenfield (no code, no org context)**:
+```
+Detected: empty directory.
+
+Starting fresh: I'll guide you through PRD -> Architecture -> Build -> Ship.
+```
+
+**For brownfield (code present, no org context)**:
+```
+Detected: existing codebase.
+
+I'll start by understanding what's here:
+  1. Code archaeology (history, conventions, risks)
+  2. Reverse-engineer planning artifacts from the code
+  3. Assess technical debt
+  4. Then we can add new work safely
+
+This is the recommended path. Proceed?
+```
+
+**For brownfield (code present, org context found)**:
+```
+Detected: existing codebase + org standards.
+
+I'll start by understanding what's here, while respecting your org's
+standards (TypeScript, AWS, Datadog, ...). Path:
+  1. Code archaeology
+  2. Reverse-engineer planning artifacts
+  3. Assess technical debt against org standards
+  4. Then add new work
+
+This is the recommended path. Proceed?
+```
+
+**For bluefield (no code, org context found)**:
+```
+Detected: empty directory + org standards.
+
+You're starting a new project within an established org. I'll constrain
+all decisions to your org's standards (TypeScript, AWS, Datadog, ...).
+Path: PRD -> Architecture -> Build -> Ship, with org standards enforced
+throughout.
+
+Proceed?
+```
+
+**Additional banner when this repo is part of a multi-repo suite** (Mode D, layered on top of A/B/E):
+```
+Also detected: this repo is part of a multi-repo suite at <suite-path>
+with N siblings.
+
+A peer agent (god-coordinator) will track suite-scope invariants
+(byte-identical files, shared standards, coordinated version table).
+Per-tier work in this repo continues as above.
+```
+
+The user sees plain language. The orchestrator internally tracks the mode
+in state.json (`mode: A | B | C | E`) for tooling but never burdens the
+user with the term. Mode D (multi-repo suite membership) is a separate
+boolean flag, not a primary mode, because every repo in a suite still
+runs one of A / B / E underneath.
+
+### Mode storage in state.json
+
+```json
+{
+  "mode": "A | B | C | E",
+  "mode-d-suite": false,
+  "mode-detected-from": [
+    "no-package-json-found",
+    "no-org-context-found",
+    "no-suite-detected"
+  ],
+  "mode-announced-as": "greenfield" // human-friendly label for output
+}
+```
+
+Modes A/B/C/E are stored for programmatic queries; `mode-d-suite` is
+true when `lib/multi-repo-detector.detect` finds the repo registered
+in a parent suite. The human-friendly label is what the user sees.
+
+### Mode A: Greenfield (auto-detected)
+- No existing code in working directory
+- No org-context.yaml
+- Run all tiers from PRD onwards
+
+### Mode B: Brownfield / Gap-fill (auto-detected)
+- Existing code OR partial `.godpowers/` artifacts present
+- May or may not have org context
+- Default path: archaeology -> reconstruct -> debt-assess -> greenfield
+  simulation audit -> greenfieldify plan and approved artifact updates ->
+  proceed
+
+**Detection logic (run this on every Mode B invocation)**:
+
+```
+For each canonical artifact path:
+  1. Check if file exists on disk
+  2. If exists: spawn god-auditor briefly to score against have-nots
+  3. If passes: mark tier as "imported" in PROGRESS.md, skip
+  4. If fails: mark tier as "in-flight" with the failures, will re-run
+  5. If missing: mark tier as "pending"
+
+Canonical paths to scan:
+  .godpowers/prd/PRD.md
+  .godpowers/arch/ARCH.md
+  .godpowers/roadmap/ROADMAP.md
+  .godpowers/stack/DECISION.md
+  .godpowers/repo/AUDIT.md
+  .godpowers/build/STATE.md
+  .godpowers/deploy/STATE.md
+  .godpowers/observe/STATE.md
+  .godpowers/launch/STATE.md
+  .godpowers/harden/FINDINGS.md
+
+Also check codebase signals (gap-fill heuristics):
+  - package.json or equivalent exists -> repo scaffold likely done, mark Repo "imported"
+  - .github/workflows/ or .gitlab-ci.yml exists -> CI exists, partial repo done
+  - tests/ or *.test.* files exist -> some build progress, suggest /god-status to verify
+  - Dockerfile + deploy config -> deploy may be done, prompt user
+
+Report findings to user before running any tier:
+  "Detected: PRD imported, ARCH missing, Roadmap imported (passes have-nots),
+   Repo imported (CI present), Build in progress. Resuming from Build."
+```
+
+### Greenfieldification checkpoint for Mode B and Mode E
+
+The greenfield simulation audit is not enough by itself. It identifies gaps;
+god-greenfieldifier actions those gaps through a controlled artifact migration.
+
+Required sequence:
+
+1. Run greenfield simulation audit.
+2. Spawn god-greenfieldifier.
+3. Write `.godpowers/audit/GREENFIELDIFY-PLAN.md`.
+4. If the plan can change product scope, design direction, architecture,
+   roadmap, stack, deploy, observe, launch, harden, org policy, or user
+   commitments, pause for user approval before rewriting canonical artifacts.
+5. After approval, update every affected artifact, not just the first artifact
+   where the gap appears.
+6. Run sync so PROGRESS.md, state.json, and SYNC-LOG.md reflect what changed.
+
+Under `--yolo`, do not bypass this checkpoint for risky changes. YOLO may only
+auto-apply greenfieldification when every planned change is a non-destructive
+rewrite-candidate and no concrete existing evidence is removed.
+
+### Mode C: Audit
+- Triggered explicitly with --audit flag
+- Build nothing
+- Run god-auditor across all existing artifacts
+- Score each against have-nots from `<runtime>/godpowers-references/HAVE-NOTS.md`
+- Produce `.godpowers/AUDIT-REPORT.md`
+
+### Mode D: Multi-repo suite (auto-detected since v0.12)
+
+- Current repo is registered as part of a multi-repo suite (siblings,
+  shared standards, byte-identical files, coordinated version table)
+- Detection: `lib/multi-repo-detector.detect(projectRoot)` returns
+  `{ inSuite: true, suitePath, role }` when a parent or sibling directory
+  contains `.godpowers/suite/suite.yaml` and this repo is listed
+- When detected, run the underlying per-repo mode (A, B, or E) as
+  normal AND set `mode-d-suite: true` in state.json
+- A peer agent, `god-coordinator`, owns suite-scope coordination via
+  `.godpowers/suite/`. The Quarterback rule still holds inside each repo;
+  god-coordinator never bypasses per-repo orchestrators
+- Per-tier additions when `mode-d-suite: true`:
+  - Read shared standards from `.godpowers/suite/STANDARDS.md` before
+    spawning planning agents
+  - Surface suite findings from `lib/suite-state.readSuiteState()` at
+    pause checkpoints
+  - When touching byte-identical or shared-standards files, emit a
+    `suite.invariant-touched` event so god-coordinator can react
+- Per-repo state.json remains the source of truth; never write to
+  `.godpowers/suite/` directly (that's god-coordinator's surface)
+
+### Mode E: Bluefield (auto-detected)
+- No existing code in current dir
+- BUT org-context.yaml found (in current dir, parent, or grandparent)
+- Run full project run with all decisions constrained by org context
+- Spawn god-org-context-loader first to load constraints
+- Run greenfield simulation audit after org-context, then run
+  god-greenfieldifier so the project run has an approved artifact plan before PRD.
+  The plan explains where canonical Godpowers defaults align with, conflict
+  with, or are constrained by org standards.
+- All downstream agents (god-stack-selector, god-architect, god-deploy-engineer,
+  god-observability-engineer, god-harden-auditor) receive the org-context
+  and respect it
+
+Record the detected mode in PROGRESS.md (machine-readable: A/B/C/E) and in
+state.json (`mode-announced-as` for human-friendly output).
+
+## Scale Detection (Tier 0 setup)
+
+Assess project description against:
+- **Trivial**: Single-file change, bug fix, config tweak. Skip planning, go to /god-fast.
+- **Small**: One feature, <1 week. Lightweight PRD, skip ARCH.
+- **Medium**: Multiple features, 1-4 weeks. Full PRD/ARCH/ROADMAP/STACK.
+- **Large**: Multiple services, 1-3 months. Add agent personas (PM, QA), optional sprints.
+- **Enterprise**: Multiple teams, 3+ months. Full personas, sprint ceremonies, compliance.
+
+Scale determines which tiers and agents activate. Record scale in PROGRESS.md.
+
+## YOLO Decisions Logging
+
+When `--yolo` flag is active, every auto-picked default at a pause point
+must be logged to `.godpowers/YOLO-DECISIONS.md`:
+
+```markdown
+# YOLO Decisions Log
+
+These decisions were made automatically because --yolo was active.
+Review and revise any that don't match your intent.
+
+## Tier 1 / Stack
+- Pause: TypeScript vs Python (within 10%)
+- Auto-picked: TypeScript
+- Reason (default): Frontend already TypeScript
+- Timestamp: [ISO 8601]
+
+## Tier 1 / Architecture
+- Pause: Monolith vs microservices for scale unknown
+- Auto-picked: Monolith
+- Reason: Lower complexity for unknown scale
+- Timestamp: [ISO 8601]
+```
+
+Append to YOLO-DECISIONS.md every time --yolo would have paused.
+
+For preflight auto-routing, append:
+
+```markdown
+## Tier 0 / Preflight
+- Pause: Select first brownfield or bluefield route from preflight findings
+- Auto-picked: [command]
+- Reason: [preflight evidence and safest-sequence rationale]
+- Timestamp: [ISO 8601]
+```
+
+## Have-Nots Reference
+
+The canonical have-nots catalog lives at `references/HAVE-NOTS.md` (115 named
+failure modes). When verifying an artifact, run the relevant tier's have-nots
+against it. When in doubt, spawn god-auditor to do the check.